Custom Help Files

You might want to provide your own documentation for pages and tags that you create. There are three ways to do this:

  • Create a CHM file using any help authoring tool. CHM files are generally considered a deprecated technology but they still work.
  • VTScada's documentation sets aside 100 help key references that you can use by creating your own UserHelp101.htm topics. These must be created in a text editor using a template supplied with the VTScada documentation.
  • You can purchase a copy of Madcap Flare and create your own documentation.

Limitations:

  • The VTScada documentation will not see your documentation. It is not possible to add links from our documentation to yours. It is not possible for our search to find your topics.
    You are welcome to add links from your topics back to the VTScada documentation, which can be done simply by pointing a URL at the file location: C:\VTScada\VTSHelp\Default.htm
  • At time of writing, custom help files created using Madcap Flare can be opened with desktop installations of VTScada and with the VIC thin client but not with Anywhere thin clients.

Process for using Madcap Flare:

  1. Obtain a copy of Madcap Flare and use it to build your help project, with the output type set to HTML5. A SideNav template is recommended.
  2. As you create CSH values in your project's alias file, create mapping IDs that are between 5000 and 10000. This will avoid conflicts with VTScada's help ID numbering system.
  3. After building your project, copy the output folder structure to the VTScada installation folder.
    (For example, if your project is named "CustomHelp", copy the output to "C:\VTScada\CustomHelp".)
  4. Open the Application Configuration dialog to the Edit Properties tab, Advanced Mode and add the following.
    Note that the value must match your folder name followed by the key word \MadCapWebHelp as shown.

  1. Click OK to save OEMHelp.
  2. Search for the property, HelpFile.
  3. Copy that property to your application, changing the value to CustomHelp\MadCapWebHelp.
    ("CustomHelp" is the example used here - use the name of your own folder.)
  4. Save the property and close the Application Configuration dialog.
  5. To call your documentation from a page add the following line to the Main state of that page (using a text editor to edit the source code of that page. See: Scripting)
SetHelp(Self(), \OEMHelp, 101);

Where 101 is replaced by your help ID number.

  1. In the VAM, select Import File Changes for your application. Import File Changes Tool
  2. Open your page. Press F1. View your documentation topic.
  3. For any tag that should use a page from your documentation, open the properties dialog and set the Help Search Key value to the appropriate CSH value from your documentation project.

You can also addWinButton calls to your page, coded to call the SetHelp function when selected.

Process for using the 100 ID values in the VTScada documentation:

Overview:

One hundred mapping ID values have been set aside in the VTScada help system, which you can use to link to topics you create. You can use these ID values with your pages or with individual tag instances. When an operator presses F1 while viewing your page, or right-clicks on a tag-linked widget and opens the Help option, your topic is displayed.

You must create the topic files, using the provided template as a guide. Working within the VTSHelp\Content\UserTopics folder, copy CustomHelpTemplate.txt to CustomHelp100.txt. Each copy must be named according to the pattern, "CustomHelp100.txt" where the numeric portion of the name (100 in this example) matches the ID value set aside for the topic. You will use that ID number for your page or tag. One hundred ID values have been set aside, therefore your topics will be named, "CustomHelp100.txt" through "CustomHelp199.txt".

While you can have any heading that you like within your topic, the menu system will continue to show the existing names. There is no way to change this that is both easy and failure-proof.

Your content cannot be added to the search feature of the documentation.
           Your topics are displayed only in response to an F1 request.

Edit your topic files:

  1. Assuming that you have installed VTScada in the folder, C:\VTScada, navigate to the folder, C:\VTScada\VTSHelp\Content\UserTopics.
  2. Copy the file, UserTopicTemplate.htm to UserTopicN.htm where N is a number from 100 to 199.
    Start with UserTopic100.txt and work through the set in order.
  3. Use a text editor, or a web page editor to open the new file, UserTopic100.txt
    Do not use MS Word, or any other word processing program that will add its own formatting characters.
  4. Search for the keyword, "+++Start"
    The first 300 or so lines in the topic are required to load the CSS files, JavaScript, menu and other parts of the VTScada help system. Do not edit anything before "+++Start".
  5. Replace the text between the <H1> header tags. Do not use headers other than <H1>.
  6. The content that you are replacing includes HTML tags and CSS style tags that show styles used in the VTScada help system. You should use these as needed for your own text and images.
    All the text from "+++Start" through to "end---", should be replaced.
    "+++Start" and "end---" should be removed.
  7. Save your file.

To link a tag to a user topic you created:

  1. Select the topic file and note the numeric portion of the name.
  2. Open the tag properties dialog and enter the number from the topic into the Help Search Key field of the ID tab.
  3. Close the tag properties dialog.
  4. To test, right-click on any widget linked to the tag, then click on "Help" in the menu that opens. The matching topic should open in your default browser.

To link a page to a user topic:

  1. Select the topic file and note the numeric portion of the name.
  2. Open the source code of the page to link to this topic.
  3. In the Main state, add the following line of code, replacing the number with the one from the file.
SetHelp(Self(), \DevHelpFile, 101);
  1. Click the Import File Changes button for this application in the VAM.

If creating a custom CHM-format help file:

You will need to obtain a third-party help authoring tool that can produce .CHM format help files.

Topic mapping ID values are created within that help authoring tool and assigned to topics there. VTScada's numbering system begins at 10,000. In addition, values 100 through 5000 are reserved. To avoid any conflict with the VTScada ID values, create mapping IDs that are between 5000 and 10000.

  1. Copy the .CHM file to the VTScada installation folder, not to the application folder.
  2. Use the advanced mode of the Edit Properties dialog to create a local copy of the property, HelpFile.

Link tags to topics in a custom CHM-format help file:

  • Open the properties dialog of a tag instance.
  • Set the Help Key property to the value of topic mapping id withing your help file, matching a topic to the tag.

Operators can now right-click on widgets linked to that tag, then click Help in the menu that appears, to view your topic.

Link pages to topics in a custom help file

To create a link between your page and a topic in a custom help file, edit the page's source code, then import file changes. You can define the help file and a specific topic for any page by adding the following line within the module's Main state:

SetHelp(Self(), Help File Name, Mapping ID value);

Replace the parameter, "Mapping ID value" with the ID value in your help file that matches the topic to open when an operator presses F1. Replace the help file name parameter using the same rules as for the HelpTopic application property:

  • If using the CHM format, set the parameter to the name of the file, including the extension. It is assumed that you will store the file in the VTScada installation folder, not in the application folder.
  • If using the Dot-Net help format, set the parameter to "MyHelpFolder\NetHelp", replacing "MyHelpFolder" with the name of the folder you created to store the help files within. Include the quotation marks.
  • If using the HTML5 format, set the parameter to "MyHelpfolder\MadCapWebHelp", again replacing "MyHelpFolder" with the name of the folder you created to store the help files within. Include the quotiation marks.
  • If using a UserTopic that you have edited in the VTScada help system, set the parameter to \DevHelpFile. Do not add quotation marks.