CSH Calls for WebHelp and WebHelp Plus

Use the following information if you are producing WebHelp or WebHelp Plus and want to incorporate context-sensitive Help (CSH) into the software application.

There are two methods you can use:

• Method 1—JavaScript Using this method requires calling a JavaScript function that Flare provides.
• Method 2—URL Using this method, you can create a hyperlink to launch the Help system.

Which Method is Best for You?

Each method has its unique benefits. Generally speaking, the JavaScript method lets you have more control, whereas the URL method is a bit more quick and simple.

One reason to choose the JavaScript method is to better control the window size and location. With the URL method, the browser window automatically starts to open at the same size and location as the previous time that browser window was opened. But if you have specified a different size and location for your output window, the window will visibly move and resize accordingly. The JavaScript method prevents this type of behavior by opening the window directly to the size and location you specified. You would set the window size and location in the skin. Then in the JavaScript call you would specify the appropriate skin.

Another benefit to using the JavaScript method is that it is required in order for the Browser Settings option to take effect. This option can be found on the WebHelp Setup tab of the Skin Editor. See Specifying Browser Settings.

Information for Developers

How to Use the JavaScript Method

1. Add a reference to the JavaScript file (which is created automatically when the author builds the output). This .js file is named after the WebHelp or WebHelp Plus output file and placed at the root level of the output folder. For example, if the output file is named "MyFirstHelp.htm," the JavaScript file is called "MyFirstHelp.js." The reference to the JavaScript file should use the following format.

   Copy

   <script type="text/javascript" src="[path of file]/csh.js"></script>

   Note Make sure you use forward slashes (/) in the src path to the file, even if the file is referenced locally.

2. Create a trigger and add the command to let users open the Help system. Here is a format that you can use to add a button.

   Copy

   <input type="button" value="Open Help System" onclick="FMCOpenHelp(ID, skin name, search string, first pick search string value );" />

   You can change the input type and the value if necessary. The most important parts that you will adjust are the elements within parentheses (ID, skin name, search string, first pick search string value).

   • ID This can be either the identifier name or value. The topic and skin associated with the ID will be used. If no skin is associated with the ID in Flare, the skin name that you provide in this command will be used.

     Alternatively, the ID may contain a topic path. In this case, the specified topic will be loaded with the skin that is specified in this command. The topic path must be relative to the Content folder of the Flare project. You also have the option of entering "null" instead of an ID to use the Help system's default starting topic.

   • Skin Name This is the name of the skin to use when opening the Help system. If a skin has been assigned to the ID in Flare and you enter a skin name in this command, the skin name in the command will take precedence. You also have the option of entering "null" instead of a skin name if you want to use the Help system's default skin or to use the skin that is associated with the CSH ID in Flare.
   • Search String This is an optional element that automatically performs a search for a specific string.
   • First Pick Search String Value This element can be used in conjunction with the search string. If you use the first pick option, you can include a true or false value. If the value is true, the first topic found with the specified search string will be opened automatically. If the value is false, the search results will simply be displayed; the first topic will not be opened automatically.

In the following example, the topic and skin associated with "Welcome" will be used. No search string information is included.

<input type="button" value="Open Help System" onclick="FMCOpenHelp('Welcome', null, null, null );" />

In the following example, the topic associated with "Welcome" will be used. "BlueSkin" will override the skin associated with "Welcome." No search string information is included.

<input type="button" value="Open Help System" onclick="FMCOpenHelp('Welcome', 'BlueSkin', null, null );" />

In the following example, the topic and skin associated with the ID value 1000 will be used. No search string information is included.

<input type="button" value="Open Help System" onclick="FMCOpenHelp(1000, null, null, null );" />

In the following example, the topic associated with the ID value 1000 will be used. "BlueSkin" will override the skin associated with ID value 1000. No search string information is included.

<input type="button" value="Open Help System" onclick="FMCOpenHelp(1000, 'BlueSkin', null, null );" />

In the following example, "Company/Employees.htm" will be used with the default skin. No search string information is included.

<input type="button" value="Open Help System" onclick="FMCOpenHelp('Company/Employees.htm', null, null, null );" />

In the following example, both the default topic and skin will be used. A search will automatically be performed for the words "quarterly report," but the first topic found in the search will not be opened automatically.

<input type="button" value="Open Help System" onclick="FMCOpenHelp(null, null, 'quarterly report', false );" />

In the following example, the default topic will be used with "BlueSkin." A search will automatically be performed for the words "quarterly report," and the first topic found in the search will be opened automatically.

<input type="button" value="Open Help System" onclick="FMCOpenHelp(null, 'BlueSkin', 'quarterly report', true );" />

How to Use the URL Method

Create a trigger and add a link to let users open a specific area of the Help system.

There is a certain amount of flexibility in terms of how you create the link and what you can include in it. Here is the basic structure of the link.

[main entry file]_CSH.htm?[search string]|FirstPick#[ID or topic file name.htm]|[skin name]

• Main Entry file_CSH.htm This is the main entry file for your output. The file name is determined by whatever you enter into the Output File field in the General tab of the Target Editor. If you do not provide a name in this field, the name "Default" will be used. After the file name, it is important that you add an underscore followed by "CSH."

  Note You do not need to include the "_CSH" portion in the file name of the topic in Flare. You only need to add " _CSH" to the web page hyperlink connecting to that topic.

• Search String This is an optional element that automatically performs a search for a specific string.
• First PickThis element can be used in conjunction with the search string. If you include the first pick option, the first topic found with the specified search string will be opened automatically. If you do not include this element, the search results will simply be displayed; the first topic will not be opened automatically.
• ID This can be either the ID name or number. The topic and skin that is associated with the ID will be used, unless you override it in this link by specifying a different skin name. If you do not want to use a map ID, you can use the topic file name.
• Topic Name This is the name of the specific topic to which you want to link. If you use this element, an ID does not need to be created. The topic path must be relative to the Content folder of the Flare project. If you do not want to use the topic name, you can use an ID.
• Skin Name If you use an ID in the link, the skin associated with that ID (if any) will be used to display the Help. However, you can specify a skin directly in the link, which will override the skin associated with that topic in the alias file.

In the following examples, these values are used:

• Default.htm = main entry file name
• 1000 = CSH ID value
• Soccer = CSH ID name
• Soccer.htm = topic in the project, at the root level of the Content Explorer
• World Cup Standings = search term
• Green = skin name

<a href="http://my.mycompany.com/Default_CSH.htm#Soccer|Green">Click here to open</a>

<a href="http://my.mycompany.com/Default_CSH.htm#1000">Click here to open</a>

<a href="http://my.mycompany.com/Default_CSH.htm#Soccer.htm">Click here to open</a>

<a href="http://my.mycompany.com/Default_CSH.htm?World Cup Standings#1000">Click here to open</a>

<a href="http://my.mycompany.com/Default_CSH.htm?World Cup Standings|FirstPick#Soccer">Click here to open</a>