Overview

The Help System is implemented in the jsHarmony and the jsHarmony Factory modules. jsHarmony provides an extensible structure for implementing a help system, and the jsHarmony Factory provides a turnkey implementation with administration screens.

jsHarmony Help Components:

Client-side Help Icons
model.helpid property on each model to define the model's help screeen
jsHarmonySite function stubs for generating the Help URL for each model

jsHarmony Factory Help Components:

User-side Help Screens
Help Administration Interface

Built-in jsHarmony Factory Help System

When using the jsHarmony Factory, the turnkey help system will work out-of-the-box.

A "Help" button is displayed in the top-right of each model, and in the Top Links next to the "Logout" button: <%-getScreenshot('jsHarmonyTutorials/ModelHelp_Standard_Cust_Listing','Help Icon')%> Clicking on the "Help" icon will open the Help Panel defined in the jsHarmony Factory config property "help_view": <%-getScreenshot('jsHarmonyFactory/Help_Listing/?help_target_code=ModelHelp_Cust_Listing','Help Panel')%> If no Help Panel is defined for the model.helpid, then a listing of all the Help Screens will be displayed: <%-getScreenshot('jsHarmonyFactory/Help_Listing/?help_target_code=','Help Listing')%> The Administration consists of two components:

Help Panel Definition (Developer-only)
Help Panel Content

The Help Panels should be defined by the developer during system design. Help Panel Administration is under the "Developer" tools: <%-getScreenshot('jsHarmonyFactory/Dev/HelpTarget_Listing','Help Panel Administration')%> The "Code" defined in the Help Panel used to associate a unique Help Screen with a model. The "model.helpid" property defines which "Help Panel" should be opened when the Help link is clicked:

{
  "table":"cust",
  "layout":"grid",
  "caption":["Customer","Customers"],
  "helpid":"ModelHelp_Cust_Listing",
  "fields":[
    {"name":"cust_id","caption": "ID"},
    {"name":"cust_name","caption":"Customer"}
  ]
}

Finally, the Help Screen itself can be managed under the "Administration" - "Help Maintenance" administration: <%-getScreenshot('jsHarmonyFactory/Admin/Help_Listing','Help Administration Listing', { unstable: 'timestamp' })%> <%-getScreenshot('jsHarmonyFactory/Admin/Help?action=update&help_id=1','Help Administration Edit', { height: 1500, unstable: 'timestamp' })%> The "Main System" and "Client Portal" checkboxes define on which sites the Help Screen will be displayed.

The Help Body is a WYSIWYG editor. Images, links, and formatting are supported.

model.helpid

The model.helpid property is used to define which Help Panel will be loaded when the help button is pressed.

{
  "table":"cust",
  "layout":"grid",
  "caption":["Customer","Customers"],
  "helpid":"ModelHelp_Cust_Listing",
  "fields":[
    {"name":"cust_id","caption": "ID"},
    {"name":"cust_name","caption":"Customer"}
  ]
}

In custom Help Implementations, this value can be any string used to identify the Help for that model.

If using tabs, and model.tabpos='top', the model.helpid for the page will be overwritten to the model.helpid of the first tab.

configFactory.help_view

The configFactory.help_view configuration property is part of the jsHarmony Factory Help implementation. The help_view property defines which Model will be opened when the Help button is clicked.

The default value for the "help_view" configuration parameter is:

help_view: {
  "main": "Help_Listing",
  "client": "Client/Help_Listing"
}

Help Views can be customized per site. The link to the Help is dynamically generated based on the model configuration; popup parameters are supported.

configFactory.help_panelid

The configFactory.help_panelid configuration property is part of the jsHarmony Factory Help implementation. The help_panelid property defines the name of the querystring parameter containing the "model.helpid" property that will be passed to the "help_view" model when the "Help" button is clicked.

help_panelid: "help_target_code"

Hiding Help

The "Help" button can be hidden by adding "help" to the model.hide_system_buttons property: <%-getScreenshot('jsHarmonyTutorials/ModelHelp_NoButton','No Help Button')%>

{
  "table":"cust",
  "layout":"grid",
  "caption":["Customer","Customers"],
  "hide_system_buttons":["help"],
  "fields":[
    {"name":"cust_id","caption": "ID"},
    {"name":"cust_name","caption":"Customer"}
  ]
}

This will not remove Help from the top-right link next to the "Logout" button. The top-right link must be changed in the template.

Custom Help System Implementation

Custom help can be implemented by extending the jshSite.help function in app.config.js:

var jshsite = jsh.Sites['main'];
jshsite.help = function(req, res, jsh, helpid, onComplete){
  //Help Link
  var helpurl = '/jsHarmonyFactory/Help_Listing?help_target_code='+encodeURIComponent(helpid);
  //Help Onclick Event
  var helpurl_onclick = "XExt.popupForm('jsHarmonyFactory/Help_Listing', 'browse', { help_target_code: "+JSON.stringify(helpid)+" }); return false;";
  return onComplete(helpurl, helpurl_onclick);
};

When the jshsite.help function is called, it is passed the model.helpid property of the current model. The function can:

Return the "helpurl" link to the target help file.
Return a "helpurl_onclick" event that will be attached to the help buttons. The "helpurl_onclick" can open a popup or perform additional processing.

On the client-side, the helpurl and helpurl_onclick are attached on model initialization, to the model help buttons, and to any element with the "toplink_help" class that does not have the "static" class.