Forum OpenACS Q&A: ANN: Context Sensitive Help System

I am pleased to announce an alpha version of a help system package.

Main features are:

• context sensitive help - you only see help for the current page
• help can be toggled on and off
• full i18n support
• package driven
• developer and user driven

This help package is fully UI driven. The reason for this is that as you can see most packages in OpenACS lack of a decent documentation. Maybe the migration from docbook to xowiki will close this gap.

Therefore I decided to develop the help system like the language package in a user driven way. Thus even if the developer doesnt provide a help for his package any user with site wide administration rights can add help to any page without any programming skills required.

Another benefit is that the help is given from users to users which itself will be more usable.

Some questions are open though:

• We need a solution to bring all locally created help texts back together.
• Where shall the help texts be stored in the local package catalog files (which I prefer, current solution) or centrally in the help package.
• How shall we integrate that in OpenACS. I personally like the way the translation mode was integrated. Therefore I would recommend the same solution for the help system. Thus there would be a toggle to add help texts (current solution). This would require some minor changes to some existing packages.
• How shall we display the help? Several ways are possible:
  • As a div-Block inside the page (current solution9
  • As a pop-up window
  • As some kind of tool tip of fancy java script solution

You may see a working example under:

madura.bwl.uni-mannheim.de:9001

Any comments appreciated.

Nima,

For display it makes sense to allow all three solutions. This sounds really interesting, thanks.

Peter, conceptually my approach is very simple.

This help system is strictly message key oriented. Thus it only works for packages that are i18n-ized. Basically every page that uses message keys can have help texts just like tool tips associated with the key. The idea behind that is very simple: For a message key mypackage.foo see whether there is a help text message key mypackage.foo_hlp and display it.

Therefore the help package doesnt require any data model itself but makes extensive use of the localisation package.

It is up to the community to decide whether this approach is acceptable. The package could be extended by providing role dependent help through further naming conventions like mypackage.foo_hlp_admin for administrators.

Now the above approach has implications that we have to keep in mind:

• Displaying the help outside of the current window requires a more sophisticated key recording solution and window synchronisation (between main and help window) than simply including the help inside the same window. Should be too difficult to be implemented.
• The help texts available strictly depends on used message keys in the current page. Thus a package wide help is not available at present.
• acs-lang is required. Help is stored in catalog files and can be brought back to cvs.
• Without the help package an OpenACS site currently would load existing help messages but never displays them. On the other hand as soon as the help system is installed it is available.
• acs-lang doesnt support storage of mime types like images. You can only use text and html and link to files available (in the package) via URL. One option to solve that is to allow the upload of files that are stored with the catalog files.

As for the package wide help I am not sure how we could provide a clean solution with a message key driven approach. I think there should be a way to categorize the help texts and provide some sort of ordering, right? How could this be done?

Same applies to search and indexing. Havent thought about that yet.

Also not quiet sure what you mean by webpage could easily link to a helppage in the catalog by providing the shortname and whether this would be possible with the above approach.

Comments are appreciated.

Very nice indeed. Ingenious way of using acs-lang.
I am going to try and look into this further. Where can I get a copy of this package ? Is it in CVS HEAD ?

My vision is to build on top of your help system with some ajax (fancy javascript).

I would have a tcl file that accepts an HTTP POST with the message key and returns the associated help text.

The help text would return as a draggable floating div that appears when (?) or "Help" is clicked.

Hi nima, using message keys is an interesting idea. I think it would probably be even simpler to just use plain xowiki pages. They have somekind of shortname sou you can easily link to them. Just mount an xowiki instance for every package and have helps texts there. In the pages itself you could have some kind of help resolver (similar to [_ xxx]) that just inserts the relevant xowiki page (or a link to it that opens in a popup).

Relevant link on modeless interaction on the web pulling from the apple human interface guidelines:
http://developer.apple.com/internet/webcontent/hideshow_layer.html

Something along these lines would be nice for this package.

Example adapted from the guideline: popups when you mouseover a link (e.g. [i] or [?] or [help] with rollover popups that are also clickable links in case the browser doesn't support the rollover or javascript is deactivated).

Hi Nima,

What's the status of this package? It seems the site with the working example is no longer up.

Is there a place where we can download it ?

I wrote some javascript with ajax for a Help System on our demo at http://solutiongrove.info/. The back end is just a simple adp/tcl file that reads the url and returns text depending on where the user is.

I would like to use this front end with your Context Sensitive Help system as the backend.

Thanks,

Ham

Ham, would it be possible to really link this up with XoWIKI Pages? You can probably tell help to provide a help link by adding a help property, which gets the name of the xowiki help page to display. As an admin you could create this page then easily. That is the quick and easy solution I come up with from the top of my head.

I don't see why xowiki do not fits for short/simple help, can you explain?