KenyaUI Integrated Help (Proposal)

This page describes a design for proposed functionality in KenyaUI

Provide an annotation that can attach context specific "help content keys" to page controllers, e.g.

@AppPage
@HelpContext("edit-patient")
public class RegistrationEditPatientPageController {...}

When page is requested, a page interceptor will parse the annotation and attach the data to the request object or page model.

When the help button is being rendered, it will read this and append it to the request URL for the help dialog, e.g. http://192.168.0.1/openmrs/kenyaemr/help.page?contextKey=edit-patient

When the help button is pressed, the dialog content is fetched dynamically from KenyaEMR as a new page request. The controller which handles this page request will get the help context key as a parameter.

It will then look for a Setting (formerly Global Property from 1.9 downwards) which provides the external help system's URL. This would be optional to accommodate installations without the external help system

@PublicPage
public class HelpPageController {
	public void controller(@RequestParam(value = "contextKey", required = false) String contextKey, PageModel model) {
		model.addAttribute("contextUrl", Context.getAdministrationService().getGlobalProperty("kenyaemr.externalHelpContextUrl"));
		model.addAttribute("contextKey", contextKey);
	}
}

If an external help system URL is provided, the help dialog view will make a client-side request (using jQuery) to fetch content from that URL, passing the context value as a request parameter, and it will display that content at the top of the help dialog. For example if the external help system URL global property is set to http://192.168.0.1/help/context then the help dialog will fetch and display content from http://192.168.0.1/help/context?key=edit-patient.

If no Setting (formerly Global Property from 1.9 downwards) is specified, then the help dialog only displays generic help from within KenyaEMR, e.g. support phone number etc.

External help system requirements

This could be implemented as any kind of web application, provided that it includes:

A root URL that returns a complete landing page - this is what users will see when they access the system directly.
Another URL that returns an HTML snippet which is suitable for inclusion in KenyaEMR's help dialog
- If no context parameter is specified, it should return general content such as a link to the landing page.
- If a context parameter is specified, it should return content specific to that key, e.g. a link to the relevant job aid.