trigger help

Trigger for reacting to the user's request for online help in a desktop application.

Declaration: trigger help
Applies to: Entity , Field
Activation: Activated by the structure editor function ^HELP. If the field-level help trigger is empty or contains a $callup instruction, the entity-level help trigger is activated. For more information, see $callup.
Default behavior: If the operation is not explicitly declared, it falls back to a default behavior:
  • In Entities, there is no default behavior
  • In Fields, the help trigger of its parent entity is invoked
Behavior upon completion: None

Description

The presence of ProcScript in the field-level help trigger overrides the entity-level help trigger.

The help trigger is one way to display information to help the user. You can also use tool tips for fields, or display HTML pages or static text in server pages and forms.

In the help trigger, help information is usually presented using the message or help statements:

  • message—displays a single line of text.
  • help/topic or help/keyword—invokes a native GUI help engine to display help information for a topic or keyword.
  • help—starts a Uniface form in which the help message is displayed.

With message or help to display a Uniface help text, it is recommended that you use the $text function to access text stored in the runtime object library. This is more maintainable than hard-coding the text, and allows the developer to localize the software by changing the language used to retrieve the text. The following example displays the help message in the message database with an identifier of H_USERNAME: 

trigger help ; of USERNAME
  help $text(H_USERNAME)
end

By defining this message for different languages in the message database, you can change the help displayed by defining a different language in the assignment file for the application. For example, the following assignment file settings cause help text to be displayed in Dutch: 

$LANGUAGE = NL
$VARIATION = TECH_PUBS

The following assignment file settings cause help text to be displayed in American English: 

$LANGUAGE = USA
$VARIATION = TECH_PUBS

This assumes that the application does not set the $language or $variation functions, and that help text has been defined in both Dutch and American English.

You may find that it helps to define the help text when you define the modeled entities and fields—if you cannot write the help text for an entity or field, you probably do not understand what it is for. It is also easier to define the code for the help trigger once, in the modeled entity or field, rather than every time it is used in a component. You can always override the model definition with a form variation.

Example: Field-Level Help

If you use a help message naming convention of FieldName_HLP, you can use the following ProcScript statement in the model definition for the field: 

help $text("%%$fieldname%%%%_HLP")

This ProcScript statement can even go in the entity-level help trigger. You can override it with a model definition for a particular field if you require it.

You can even put this in the default ProcScript for the help trigger.

Example: Entity-Level Help

The following example shows how the help trigger can be used to display help information for the entity USERS: 

trigger help
help $text(USERS)
end; help

You can implement ProcScript that provides help according to the value of certain fields. For example: 

trigger help
if (GENDER = "M")
   help $text(MALE_RETIREMENT)
else
   help $text(FEMALE_RETIREMENT)
endif
end; help

Related Topics