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

Posted by Nima Mazloumi on
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:

Any comments appreciated.

Posted by Nima Mazloumi on
Oh, I forgot: you dont need to register. simply goto the above site and press the help link.
Posted by Dave Bauer on

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

Posted by Peter Alberer on
hi nima, i think this is a really good initiative. as far as the display is concerned, i think there should be a help browser similar to the windows help, where there is a left frame with the help toc (could be a toc across all packages and their help topics) and a right frame with the content.

there could also be search and indexing for the help based on available topics. any webpage could easily link to a helppage in the catalog by providing the shortname.

Posted by Nima Mazloumi on
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 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.

Posted by Malte Sussdorff on
I really like how this works. Ideally it should incorporate the help texts of ad_form.

As for the display, I do agree with Peter but for the moment having 1 and 2 as an option should be sufficient. Obviously though, if you go with 2, you should refresh the help window whenever you go to a new page.

As for bringing those together again. Well, as you are storing the help as an I18N message anyway, the same process should apply, whatever it might turn out to be.

Package wide help support: This is what /doc is there for. So package wide documentation should be handled either using the Wiki and then exported to /doc or by just adding documentation to /doc. If you really want this to be handled the same way just create an index.adp in /www/doc with # my-package.package_wide_help#.

As your package is non intrusive, the community does not have to come up with a "yes" or "no" with regards to liking your package. Those who like your approach can just make use of it. It only becomes an issue when we commit message keys back to the translation server, but a quick change in acs-lang with a parameter "UseHelpKeysP" set to "0", that surpresses import/export of help message keys, should take care of that problem. And if you want to be really non intrusive, don't make this a parameter but write a callback for the import/export functions in acs-lang that would do the same (though this is a little bit more tricky, I have to admit).

Posted by Hamilton Chua on
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.

Posted by Nima Mazloumi on
Hamilton: this is what I am working on currently. Check out If you enter acs-kernel.Main_Site you get what you wanted.
I will make the package available soon. I need to clean up everything.
Posted by Peter Alberer on
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).
Posted by Nima Mazloumi on

I thought about that option but decided to go with acs-lang for the moment due to the many features I will get for free like i18n, translation mode, catalog export, key history, conflict resolution...

My primary goals is to synch local installations with a central translation server.

Posted by Carl Robert Blesius on
Relevant link on modeless interaction on the web pulling from the apple human interface guidelines:

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

Hello Nima!

What about this package?

We´ll like to test it.


Posted by Hamilton Chua on
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 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.



Posted by Nima Mazloumi on
The work was a quick hack to see how we could use acs-lang for a context sensitive help. I never
created something for production use because of some problems that had to be addressed like
a mechanism to order the localized help messages or categorize the help messages or role specific
help. I never published it. One solution could be based on xowiki for a more flexibel help system.
Posted by Malte Sussdorff on
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.
Posted by Dave Bauer on
Why use Xowiki? Xowiki is nice, and is probably a better tool for documentation, as opposed to help. Help should hopefully be short and simple.

I want to definitely implement something into core OpenACS. I think its very important to give users context appropriate information and it should be part of core. That's why Xowiki really isn't the right answer. Maybe there is a way to combine short help, with xowiki for a full documentation type solution.

Posted by Rocael Hernández Rizzardini on
I don't see why xowiki do not fits for short/simple help, can you explain?