Jump to:

Problem/Motivation

As part of#1289090: [meta] Improve search/navigation for d.o community docs
we reached consensus that we would like to add +/- "MSDN classic" style navigation to the right sidebar book navigation on Documentation pages on Drupal.org. This would allow people to drill down through the book without incurring page loads. An example of what this looks like on MSDN:

Proposed resolution

Develop or locate a module that adds this to the navigation if JavaScript is enabled, and degrades gracefully back to the current navigation if JavaScript is not enabled. The solution also needs to pass review by our Drupal Usabilty and Accessibility teams.

Remaining tasks

Test the Advanced Book Blocks module to see if it will work with our existing very large book structures, and to verify that it is accessible and usable.

If so, get it deployed on Drupal.org, and someone will also need to consider a Drupal 7 port of that module very soon.

If not, develop a new module, for Drupal 6/7, that does what we need.

User interface changes

Visitors to the Drupal.org Community Documentation will be able to navigate through the book hierarchy without incurring page loads. They will be able to click +/- (or something like that) to expand/contract sections of the book hierarchy and find the pages they are interested in.

API changes

None.

Comments

A note about the Advanced Book Blocks module... I looked through the issue queue for the module, and it looks like it has some bugs, and it may need some patches to be a replacement of the current Book navigation... Not sure, needs to be tested.... So, it might take some work to get it to do what we want it to do... all the same, it might be easier than starting from scratch. Then again, it might not.

The other possibility would be to start over from the API of JQuery Menu (which is what Advanced Book Blocks is using, and it comes from the same developer) and apply it in a different way to the current Book navigation. That might actually be easier, and JQuery Menu is already available for Drupal 7, which is an advantage.

I took a quick look at Advanced Book Blocks, which as you say is based on JQuery Menu. The description of JQuery Menu says:

"Unlike active menus, which makes ajax calls to fill in the lower level menus when you click the plus symbol, Jquery menu creates the menu in full on the initial page load. I personally have used active menus for several months and have found that those ajax calls sometimes fail, and are not as stable as jquery. "

Unless someone has a brilliant remediation, non-ajax doesn't seem to fit well with a menu that loads for every page and contains 1000's of items. Could be a candidate for stand-alone page though?

On the plus side, the fact that ABB exists, and has some adoption, says that there's some acceptance for the idea, and also provides some examples that are worth studying for clues to what works, UI and style wise.

Here's a link to Active menus, which exemplifies a client hierarchical thing using Ajax to request additional child nodes, and the server-side to handle that.http://drupal.org/project/activemenu

Also, here's jQuery File Tree which may be useful input to this task, in the sense that it portrays a tree, calls the server to fill in descendant nodes, and has server-side code ("connector scripts") to manage that end of the apparatus, albeit for files rather than book-structure data.

Another feature that would be useful is that this expand/contract nav show you (with bold formatting or something like that) the trail to your current page, because you might sort of lose your place with all the expand/collapses. (this is coming from comments 30-33 on #1289090: [meta] Improve search/navigation for d.o community docs

Anyway... The next thing we need is for someone to take on the task of building this. gwideman? Anyone else?

Just putting another recommendation out there for you. Take a look at the admin module approach, which is also used as the navigation structure for OpenAtrium within the notebook feature.

One of the problems with large documentation structures is the length of navigation when expanded. This is treated in various ways with the traditional "+/-" approach, such as collapsing all menus that were open when another is opened. In my opinion non of these works very well and you still get very long structures.

The Admin module approach is much different; it takes the approach that you selected a path for a reason and you'd like to focus on it until it dead ends for you. Then if you want to traverse back, you essentially select the point you'd like to get back to focusing on. I think this approach has a lot of advantages, such as keeping the menu smaller in length and focused more on the path you've chosen.

For some this can take a few times to get used to, but it's a quick learn in my opinion.

jhodgdon:
Yes I did work on it a little bit but later couldn't as went on vacation & stuff.
Actually what I did, picked 'abb' module & started working/kinda porting to 7.x on it but under different namespace[just as to generalize module to around issue]. I thought this approach would be ok.
Currently, don't think code is of much worth[as it has bugs, half-baked etc] so should i upload it to sandbox so you have a look or something or totally different thoughts?

Does the Advanced Book Blocks module do what we want for this issue, and does it work for Drupal 6.x? Task #1 in the issue summary was to test this module and see if it will support large books and if it's accessible, and evaluate whether it would be at least a good starting point. Do you have an opinion on that?

Regarding a Drupal 7 port of the module, the most appropriate thing to do would probably be to zip up your code and attach it to this issue on the ABB module, with a comment saying what works and what doesn't:#1037658: Advanced Book Blocks:l Drupal 7 port

Oh, also I'm wondering if you want to keep working on this nmugdal? If you do, great! Even if you don't have a huge amount of time, your contribution would be welcome. And as far as I know, no one else has shown interest in taking it over.

If you're not still interested in working on this, thanks for what you've done! And please un-assign the issue.

#12
Yes 'abb' module works for 6.x & I created around 100 raw entries of book but only a single page & attached to navigation block. May be this isn't so called large amount but it worked fine as we wanted it to be. It can be good starting point because it integrates with jquery_menu already & has structure ready [also as stated in #3, non-ajax calls & on multiple pages are doubtful ] But is there any much good point in reinventing wheel as it gonna be a wheel/circle afterall :-)
okay will attach code to that issue.
#13, I think i can/may work on it :-) but let me just un-assign it, for the sake of someone quicker wants to take it over, then one can.