Inline Help Framework
This project describes the creation of a framework to provide inline help information within portlets. With this system portlets will be able to provide links within the portlet screens to detailed help on how to use a given feature. The help contents will be shown within the current page to prevent losing the context.
Note: this project needs the Web Interface to modify Resource Bundle Messages to be finished first.
The inline help framework has the following requirements:
- It should be very easy for the developer to add help hooks, that is to signal points where help could be added, but without requiring the help contents to be written at that time.
- It should be possible for the portal administrator to modify the help contents at any time through the web UI
- It should be possible for the portal administrator to provide translations of the help system in several languages. The appropriate language translation should be shown based on the current user's preferences.
This project has been inspired by the help systems of other cms systems such as Moodle and Drupal and has been extended to provide the manageability and extensibility required in a portal environment
Initial Project Scope#
Implement the simplest solution that could possibly work.
Discussion of Design/Implementation Approach#
The help framework is divided in two modules:
- Inline Help Hooks: provides a way for developers to specify in which pages it would be a good idea to offer the user a detailed explanation of the purpose of a given screen, form field, etc. Each hook must be uniquely identified.
- Help Content Management: provides a way for portal administrators to edit the help contents and to associate them to certain hooks.
Inline Help Hooks #
A good solution to implement Inline Help Hooks could be to implement a taglib that the developer can use to identify a hook. It might be a good idea to namespace the identifiers within the scope of each portlet by adding an extra attribute, for example:
<help:hook portletName="community" id="assign-community-role-step-1">help</help:hook>
If there is help content provided for the specific hook the text inside the tag will be shown to the user otherwise the taglib won't produce any output. When the text is shown, clicking on it (or hovering it) will show the content.
An icon might be shown either added to the text or instead of it by using the attribute icon="true".
The interaction method can be selected through an attribute called 'interaction' whose values are:
The taglibrary could also provide some extra attributes to control how the help content will be shown. For example, it could have an attribute called style with the following values:
- inline: the content is added inline, pushing existing page elements down (as Drupal does it)
- float: the content is shown as a floating div, hiding contents underneath
Note: I'm not sure if it makes sense to have both style and interaction. If I had to choose I prefer having interaction and map click to inline and hover to float. Jferrer|Jferrer 04:38, 3 February 2007 (PST)
Help Content Management #
The help contents will be managed by using the existing Message Bundle infrastructure as follows:
- Liferay Portal will include the default inline help messages using the pointers to files. One file with HTML extension will be used per message to allow easy edition.
- The Web Interface to modify Resource Bundle Messages will be used to allow portal administrators to edit those messages through a web UI.
Another requirement should be to ensure that this framework is available to those developing portlets as deployable WARs.
Good point Mike. This is a great added-value to portlet developers.
Jferrer|Jferrer 04:53, 3 February 2007 (PST)
My vote goes for integrating help as language messages
When I first wrote this proposal I was in favour of the first implementation approach (integration with Journal), but the more than I think about it, the more that I like the second implementation alternative (adding inline help as messages). Here are some thoughts that I've had about how it would work:
- Create a new file called InlineHelp.properties along side Language.properties
- Make the web interface to edit this messages smart so that when the text is longer than a given size it shows a textarea instead of an text field to edit it.
- Make it even smarter so that if it detects HTML inside it shows a simple HTML editor to edit the value.
Jferrer|Jferrer 04:53, 3 February 2007 (PST)
How about access from Web Developed front ends?
There should be a way to obtain the same behavior through some form of js interface. In fact, I think, were possible, we should consider adding a js front end on top of our taglib features.
Rotty|Rotty 08:37, 4 February 2007 (PST)
We can implement the API for the messages as a Service and leverage the new extensions that are being made to ServiceBuilder to expose that as a REST interface that return JSON.
Jferrer|Jferrer 12:59, 6 February 2007 (PST)
Decided implementation strategy
We have finally decided to leverage the Web Interface to modify Resource Bundle Messages to implement the inline help framework. I've just made the necessary to the proposal according to this.
Jferrer|Jferrer 13:00, 6 February 2007 (PST)