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

Collapse
5: Re: ANN: Context Sensitive Help System (response to 1)
Posted by Nima Mazloumi on 04/05/06 04:25 AM
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.

Collapse
9: Re: Re: ANN: Context Sensitive Help System (response to 5)
Posted by Peter Alberer on 04/05/06 01:03 PM
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).