On-line Help Customization
--------------------------

.. note::

   The customization to on-line help discussed here refers
   to the data in the ``data/GeneralHelp`` model.

The online help information that is available can include general
and field-level information. This information can be added in the following
ways:

* On the design input form of the model. In this way the creator of a 
  model can include its on-line help information. Field-level help 
  is also shown as a tool-tip pop-up in the instance input form of the 
  model.
* In a Field Display Policy that applies to the model. In this way the
  default information on the model can be overridden if the Field Display
  Policy is applied to the model. A Field Display Policy can be associated
  with a model from its access in the Menu Layout.
* If write access to the ``data/GeneralHelp`` model is available, instances
  of this model can be marked as information to display on the on-line help
  for a model. This is done by adding Model Overwrite Details array 
  instances to a ``data/GeneralHelp`` model instance.

Role-based access on models and model fields, as well as Field Display
Policies for models can be used to customize a user's view of the
available on-line help. 

Instances of the ``data/GeneralHelp`` model created at a selected hierarchy
level provide hierarchy-specific content. If the name of the instance
of ``data/GeneralHelp`` at a hierarchy level is the *same* as that of an
existing default instance, the default instance is replaced at the relevant
hierarchy level.

Instances of the ``data/GeneralHelp`` model also contain a language code.
If the user's language corresponds with the language code, then this instance
is displayed. In the case where an instance is to be translated, a new instance
can be created where:

* The instance ``language_code`` is updated to the new language, for example
  ``fr-fr``.
* Instance names should be unique.

If write access to the ``data/GeneralHelp`` model is available (contact VOSS), new help instances can
be added and existing help instances can be modified. The process is
summarized in the list below:
  
* The menu position of the instance (the value ``-1`` will hide an instance).
  The list of instances can be sorted on the menu position column to show
  the order in which they will display on the General Help list on the Help
  browser tab.
* The display of an instance as a part of the model detail help of one or 
  more selected models by adding **Model Overwrite Details** array instances 
  to a ``data/GeneralHelp`` model instance. Options are available to:

  * Modify the title of the model help.
  * Modify the title of the General Help instance.
  * Show or hide the model help information (as obtained from the model 
    or Field Display Policy).
  * Specify the position of the General Help instance relative to the
    model help information.

If more than one General Help instance is set to override the *same*
selected model, *all* these overrides are applied where the positioning 
does not conflict. If positioning conflicts, the positioning of the 
*first* of the General Help instances (sorted alphabetically by
instance name) is used.

If formatting is required in a new General Help model instance, the
content can be written as ReStructured Text 
( http://en.wikipedia.org/wiki/ReStructuredText ). 

Note that:

* The Restructured Text is added as a *single string* in the JSON
  format file (line breaks in the text are to be replaced by the JSON
  escaped equivalent). This will be seen in the file when the
  ``data/GeneralHelp`` instance is exported.
* Model descriptions are also pop-up tooltips, so Restructured Text
  is not supported in attribute descriptions - either in the model or
  Field Display Policy.
* There is no support for local image references, but remote references
  to images can be added in the Restructured Text by adding the URL to it.


.. |VOSS Automate| replace:: VOSS Automate
.. |Unified CM| replace:: Unified CM