CSH Calls for WebHelp and WebHelp Plus—Developers

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 for WebHelp Output.

1. Help Author -Add a header file to your project.
2. Help Author - Add an alias file to your project.

3. Help Author - In the Alias Editor, create and assign an identifier for the topic that you want to link to from the CSH call.

   For example, if you have a topic called "Welcome.htm," you might create a new identifier and also name it "Welcome." Then you might assign a value of "1000" to it. You would make sure that the topic "Welcome.htm" is assigned to the identifier.

   Finally, an optional step in the Alias Editor is to assign a skin to that identifier. However, you can bypass this step and specify a skin later when you create the actual JavaScript, or you can choose not to select a skin at all.

4. Help Author - Build your Help system using a WebHelp target and publish the output files to the final destination.

5. Software Developer - 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 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: <script type="text/javascript" src="path and name of file.js"></script>.

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

6. Software Developer - 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:

<input type="button" value="Open Help System" onclick="FMCOpenHelp( ID, SkinName, SearchString, SearchStringValue );" />

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, SkinName, SearchString, SearchStringValue).

• ID This is the CSH identifier that the author created in Flare (see Step 3 above). This can be either the identifier name or value. The topic and skin that is 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.
• SkinName 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 (see Step 3 above) 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.
• SearchString This is an optional element that automatically performs a search for a specific string.
• FirstPick This element can be used in conjunction with the "SearchString." If you use the "FirstPick" 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.

examples

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 identifier 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 identifier value 1000 will be used. "BlueSkin" will override the skin associated with identifier 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 );" />

The method requires a hyperlink to the WebHelp output file. A hash value is used to specify the starting topic or identifier to use when launching the Help system.

1. Help Author -(Optional) Add a header file to your project.
2. Help Author - (Optional) Add an alias file to your project.

3. Help Author - (Optional) In the Alias Editor, create and assign identifiers for the topics that you want to provide links to. If you do not want to create a header file, alias file, and identifiers for topics, you can instead use the file names for the topics to which you want to link.

   An optional step in the Alias Editor is to assign a skin to that identifier. However, you can bypass this step and specify a skin later when you create the actual link, or you can choose not to select a skin at all.

4. Help Author - Build your Help system using a WebHelp target and publish the output files to the final destination.

5. Software Developer - Create a trigger and add a hyperlink 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:

PathToOutput/OutputFileName_CSH.htm?SearchString|FirstPick#MapID or TopicName.htm|SkinName

Not all of the parts of this structure are necessary; some are optional. The parts that are always required are: (1) OutputFileName_CSH.htm and (2) MapID or TopicName.htm.

Following are explanations of the different elements of this structure:

• PathToOutput You may need to provide the path to the main entry file of the output, depending on its location in relation to the file where the link is located. If the file containing the link and the main entry file of your output are located in the same folder, you do not need to include a path.

• OutputFileName_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.

• SearchString This is an optional element that automatically performs a search for a specific string.
• FirstPick This element can be used in conjunction with the "SearchString." If you include the "FirstPick" 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.
• MapID This is the CSH identifier that you created in Flare (see Step 3 above). This can be either the identifier name or value. 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 name (see below).
• TopicName This is the name of the specific topic to which you want to link. If you use this element, you do not need to create an identifier as described above. 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 a map ID (see above).
• SkinName If you use a map 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.

examples

In the following examples, "MyWebHelp" is the main entry file name and "MyTopic" is the identifier name; a search string is not included:

Code:

<a href="MyWebHelp_CSH.htm#MyTopic" target="MCWebHelp">Open the Help system</a>

URL:

http://my.website.com/MyWebHelp_CSH.htm#MyTopic

In the following examples, "MyWebHelp" is the main entry file name and "1000" is the identifier value; a search string is not included:

Code:

<a href="MyWebHelp_CSH.htm#1000" target="MCWebHelp">Open the Help system</a>

URL:

http://my.website.com/MyWebHelp_CSH.htm#1000

In the following examples, "MyWebHelp" is the main entry file name and "MyTopic.htm" is the destination file name; a search string is not included:

Code:

<a href="MyWebHelp_CSH.htm#MyTopic.htm" target="MCWebHelp">Open the Help system</a>

URL:

http://my.website.com/MyWebHelp_CSH.htm#MyTopic.htm

In the following examples, "MyWebHelp" is the main entry file name, "MyTopic.htm" is the destination file name, and "MySkin" is the name of the skin; a search string is not included:

Code:

<a href="MyWebHelp_CSH.htm#MyTopic.htm|MySkin" target="MCWebHelp">Open the Help system</a>

URL:

http://my.website.com/MyWebHelp_CSH.htm#MyTopic|MySkin

In the following examples, "MyWebHelp" is the main entry file name, "World Cup Standings" is the search string, and "1000" is the identifier value (the first topic found in the search will not be opened automatically):

Code:

<a href="MyWebHelp_CSH.htm?World Cup Standings#1000" target="MCWebHelp">Open the Help system</a>

URL:

http://my.website.com/MyWebHelp_CSH.htm?World Cup Standings#1000

In the following example, "MyWebHelp" is the main entry file name, "World Cup Standings" is the search string, "FirstPick" indicates that the first topic found in the search will open automatically, and "MyTopic" is the identifier name:

Code:

<a href="MyWebHelp_CSH.htm?World Cup Standings|FirstPick#MyTopic" target="MCWebHelp">Open the Help system</a>

URL:

http://my.website.com/MyWebHelp_CSH.htm?World Cup Standings|FirstPick#MyTopic

In the following example, "MyWebHelp" is the main entry file name, "World Cup Standings" is the search string, "FirstPick" indicates that the first topic found in the search will open automatically, "MyTopic.htm" is the destination file name, and "MySkin" is the name of the skin:

Code:

<a href="MyWebHelp_CSH.htm?World Cup Standings|FirstPick#MyTopic.htm|MySkin" target="MCWebHelp">Open the Help system</a>

URL:

http://my.website.com/MyWebHelp_CSH.htm?World Cup Standings|FirstPick#MyTopic|MySkin