CSH Calls for HTML5 Output

Use the following information if you are producing HTML5 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 Setup tab of the Skin Editor. See Specifying Browser Settings.

If you use products like Fortify and Veracode to run security scans on your output, having JavaScript files in your HTML5 target might prompt security warnings when scanning it. If security warnings are displayed during these scans, you may want to exclude JavaScript files from your output. See Excluding JavaScript for CSH Calls in HTML5 Output.

Information for Developers

How to Use the JavaScript Method for CSH Calls

1. Add a reference to the JavaScript file (which is created automatically when the author builds the output). This .js file should be named "csh.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="MadCap.OpenHelp(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 ID name or number. The topic (or micro content phrase) 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="MadCap.OpenHelp('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="MadCap.OpenHelp('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="MadCap.OpenHelp(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="MadCap.OpenHelp(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="MadCap.OpenHelp('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="MadCap.OpenHelp(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="MadCap.OpenHelp(null, 'BlueSkin', 'quarterly report', true );" />

How to Use the URL Method for CSH Calls

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, although not all of the information shown below is required.

[main entry file].htm#cshid=[ID number, ID name, or topic path/name]&searchQuery=[search string]&firstPick=true

After #, you can specify any combination of the parameters (cshid, searchQuery, firstPick), separated by ampersands (&). The order of the parameters does not matter.

• Main entry file Provide the path to the main entry file for the 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.

• cshid This can be either the identifier name or number. The topic (or micro content phrase) and skin that is associated with the ID will be used (unless you override it in this link by specifying a different skin name).

  Alternatively, you can enter the path and 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.

• searchQuery This is an optional element that automatically performs a search for a specific string.
• firstPick This 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.

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

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

<a href="http://my.mycompany.com/Default.htm#cshid=1000&searchQuery=World Cup Standings&firstPick=true">Click here to open</a>

<a href="http://my.mycompany.com/Default.htm#cshid=Soccer&searchQuery=World Cup Standings&firstPick=true">Click here to open</a>

<a href="http://my.mycompany.com/Default.htm#cshid=Soccer.htm&searchQuery=World Cup Standings&firstPick=true">Click here to open</a>