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:
MSDN classic navigation

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.

One possible module to test out: http://drupal.org/project/advancedbookblocks

Remaining tasks

  1. 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.
  2. If so, get it deployed on Drupal.org, and someone will also need to consider a Drupal 7 port of that module very soon.
  3. 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

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

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.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue tags: +docs infrastructure

duh, forgot tag.

gwideman’s picture

gwideman CreditAttribution: gwideman commented

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.

-- Graham

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Priority: Normal » Major

Good call on that one, that won't work for us with this many pages!

So it sounds like we need to develop our own module. Any takers?

gwideman’s picture

gwideman CreditAttribution: gwideman commented

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.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

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?

nmudgal’s picture

nmudgal CreditAttribution: nmudgal commented
Assigned: Unassigned » nmudgal

Talked to jennifer on irc. I will be working on it and link back sandbox project, if it is required to create one, after doing some research on existing solutions.
So assigning it to myself.

mshaver’s picture

mshaver CreditAttribution: mshaver commented

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’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

RE #8 - this idea should be brought up on the parent issue
#1289090: [meta] Improve search/navigation for d.o community docs
because it's a completely different idea from what we already decided to do. We would need to evaluate and discuss there.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

nmugdal: Are you still working on this, and if so, can you give us a status update? Thanks!

nmudgal’s picture

nmudgal CreditAttribution: nmudgal commented

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?

Thanks

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

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

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

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.

nmudgal’s picture

nmudgal CreditAttribution: nmudgal commented
Assigned: nmudgal » Unassigned

#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.

Thanks.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Thanks for the update! Maybe I can install the module on a 6.x drupal.org clone and we can try it out there, and perhaps get reviews by the usability and accessibility teams.

nouriassafi’s picture

nouriassafi CreditAttribution: nouriassafi commented

You may check a Drupal 7 port of ABB:
http://drupal.org/sandbox/nouriassafi/1576288

CPJS’s picture

CPJS CreditAttribution: CPJS commented

No other module yet to support this feature in Drupal 7?

Anonymous’s picture

Anonymous (not verified) CreditAttribution: Anonymous commented

nouriassafi's port of Advanced Book Blocks works just fine—I have it running on multiple production sites (e.g. http://meaningness.com/).

It's not a complicated piece of code. I don't know how it would scale to thousands of menu items, but a few hundred shouldn't be an issue.

nouriassafi, perhaps you'd like to initiate the process for taking over an abandoned module? So that an official 7.x release can go out.

Anonymous’s picture

Anonymous (not verified) CreditAttribution: Anonymous commented
Issue summary: View changes

typo fix in tag

LeeHunter’s picture

LeeHunter CreditAttribution: LeeHunter commented
Issue tags: +Usability
HansKuiters’s picture

HansKuiters CreditAttribution: HansKuiters commented

Agree with #18. You can use the port for extra book menu's. I do get an error on saving the blokcs. Has something to do with the term settings in that block, no time yet to figure it out.