<!-- 
/*
Copyright 2017 apHarmony

This file is part of jsHarmony.

jsHarmony is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

jsHarmony is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this package.  If not, see <http://www.gnu.org/licenses/>.
*/
-->
<script type="text/x-tutorial-info">
{
  "Title": "Help System",
  "Menu": ["Models","Models Overview"]
}
</script>

<h3>Overview</h3>
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.<br/>
<br/>
jsHarmony Help Components:
<ul>
  <li>Client-side Help Icons</li>
  <li>model.helpid property on each model to define the model's help screeen</li>
  <li>jsHarmonySite function stubs for generating the Help URL for each model</li>
</ul> 

jsHarmony Factory Help Components:
<ul>
  <li>User-side Help Screens</li>
  <li>Help Administration Interface</li>
</ul>

<h3>Built-in jsHarmony Factory Help System</h3>
When using the jsHarmony Factory, the turnkey help system will work out-of-the-box.<br/>
<br/>
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:
<ul>
  <li>Help Panel Definition (Developer-only)</li>
  <li>Help Panel Content</li>
</ul>

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:
<pre>
{
  "table":"cust",
  "layout":"grid",
  "caption":["Customer","Customers"],
  "helpid":"ModelHelp_Cust_Listing",
  "fields":[
    {"name":"cust_id","caption": "ID"},
    {"name":"cust_name","caption":"Customer"}
  ]
}
</pre>
Finally, the Help Screen itself can be managed under the "Administration" - "Help Maintenance" administration:
<%-getScreenshot('jsHarmonyFactory/Admin/Help_Listing','Help Administration Listing')%>
<%-getScreenshot('jsHarmonyFactory/Admin/Help?action=update&help_id=1','Help Administration Edit', { height: 1500 })%>
The "Main System" and "Client Portal" checkboxes define on which sites the Help Screen will be displayed.<br/>
<br/>
The Help Body is a WYSIWYG editor.  Images, links, and formatting are supported.

<h3>model.helpid</h3>
The model.helpid property is used to define which Help Panel will be loaded when the help button is pressed.
<pre>
{
  "table":"cust",
  "layout":"grid",
  "caption":["Customer","Customers"],
  "helpid":"ModelHelp_Cust_Listing",
  "fields":[
    {"name":"cust_id","caption": "ID"},
    {"name":"cust_name","caption":"Customer"}
  ]
}
</pre>
In custom Help Implementations, this value can be any string used to identify the Help for that model.<br/>
<br/>
If using tabs, and model.tabpos='top', the model.helpid for the page will be overwritten to the model.helpid of the first tab.

<h3>configFactory.help_view</h3>
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.<br/>
<br/>
The default value for the "help_view" configuration parameter is:
<pre>
help_view: {
  "main": "Help_Listing",
  "client": "Client/Help_Listing"
}
</pre>
Help Views can be customized per site.  The link to the Help is dynamically generated based on the model configuration; popup parameters are supported.

<h3>configFactory.help_panelid</h3>
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.
<pre>
help_panelid: "help_target_code"
</pre>

<h3>Hiding Help</h3>
The "Help" button can be hidden by adding "help" to the model.hide_system_buttons property:
<%-getScreenshot('jsHarmonyTutorials/ModelHelp_NoButton','No Help Button')%>
<pre>
{
  "table":"cust",
  "layout":"grid",
  "caption":["Customer","Customers"],
  "hide_system_buttons":["help"],
  "fields":[
    {"name":"cust_id","caption": "ID"},
    {"name":"cust_name","caption":"Customer"}
  ]
}
</pre>
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.

<h3>Custom Help System Implementation</h3>
Custom help can be implemented by extending the jshSite.help function in app.config.js:
<pre>
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);
};
</pre>
When the jshsite.help function is called, it is passed the model.helpid property of the current model.  The function can:
<ul>
  <li>Return the "helpurl" link to the target help file.</li>
  <li>Return a "helpurl_onclick" event that will be attached to the help buttons.  The "helpurl_onclick" can open a popup or perform additional processing.</li>
</ul>

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.