Replace framesets with xsl:includes and javascript to toggle visibility

[stiemannkj1]

In the latest StackOverflow Podcast (24:56-25:49), SO devs complain extensively about framesets and how framesets make it hard to create links to documentation. I propose that we remove framesets from VDLDoc and replace them with with xsl:includes and javascript to toggle visibility of elements. Here is a prototype of the improvement. I know this is a big change, so I wanted to get feedback before just changing the code. Is this too much of a change? Am I missing any big issues that this kind of change would cause?

[stiemannkj1]

@BalusC, what do you think?

[BalusC]

Go ahead. They're a leftover from TLDDoc (and originally Javadoc) and I also dislike them :)

Related: http://mail.openjdk.java.net/pipermail/javadoc-dev/2013-August/000071.html

[stiemannkj1]

Sounds good. Unfortunately I probably won't be able to do this anytime soon.

[stiemannkj1]

I'm making some slow progress on this task here: https://github.com/stiemannkj1/vdldoc/tree/remove-framesets-12

[stiemannkj1]

@BalusC,
This is pretty much done. Check out a running example here: https://stiemannkj1.github.io/vdldoc/index.html

Since this is such a big change, I wanted to mention some design decisions I made while making these changes:

1. I tried to use as little JavaScript as possible and make it as backwards compatible as possible. As far as I know, the JavaScript methods that I used are compatible with Chrome 1, FF 1, and IE 5.5. On top of that, I added <noscript> styles that expand all namespace lists when JavaScript isn't available to toggle them (TODO need to retest this).

2. Although the frame pages are not needed anymore because of the sidebar, I default to generating a page for each of them to ensure that links are not broken. For example, if someone links to alltags-frame.html for some reason, they will now hit a page with the same content as index.html. Compare the results of these links:

   • Omnifaces alltags-frame.html: http://omnifaces.org/docs/vdldoc/current/alltags-frame.html
   • Liferay Faces alltags-frame.html: https://stiemannkj1.github.io/vdldoc/alltags-frame.html
   • Liferay Faces index.html: https://stiemannkj1.github.io/vdldoc/index.html

   I also added an option to disable this feature. I could have done a JavaScript redirect from these pages, but it seems like that might be bad for SEO. If you want me to do a JavaScript redirect, I can easily change that, but ultimately, I think a redirect would be the responsibility of the server owner (so they could do a full "301 Moved Permanently" redirect).

3. I added an option to hide the sidebar, but I didn't add any methodology to remember if it's hidden between pages. The only way I can see to do this is either generate all pages twice (once with sidebar showing and once without) or set and read a url param from JavaScript to deal with it. I wasn't sure that was appropriate or necessary (and both seemed like a lot of busywork) so I avoided it.

4. I tried to keep the CSS consistent between the new sidebar and the old frames. I only added a little CSS, and I reused most of the CSS from the frames. If there are any improvements that you think I can make, let me know.

5. I upped the version to 3.0 since this is such a big change. I think it might be a good idea to release 2.2 (I've added some minor commits to it) before merging these changes.

Here's the current diff if you are interested: stiemannkj1/vdldoc@master...stiemannkj1:remove-framesets-12.

Here's a diff between vdldoc generated by 2.2-SNAPSHOT and 3.0-SNAPSHOT: https://gist.github.com/40fdf6d5b5d6b5c2a2ab79670ec53c08

Let me know if you have any reservations. If not, I'll commit this to master some time next week.

[stiemannkj1]

It might be worth adding an Expand All/Collapse All toggler (link) for the component namespaces as well. I'll probably add that in a future commit.

[BalusC]

Good step forward as to JS, but UI (CSS) really needs work. It looks off.

[stiemannkj1]

Thanks. I agree. I will try to rework the CSS at some point. I'm not really sure what to go for except to make it similar to the old version. If you have anything in mind, let me know.