Custom Help Files

Earlier versions of VTScada documented the use of CHM-format help and a system for adding your own content to one of 100 user-defined topic files. Both systems continue to be supported for backward compatibility but are not recommended for new development work. (Customers whose custom help files are only in CHM format may continue to use calls to the Help function.)

The VTScada documentation is built using Madcap Flare®, with the output type set to HTML5. You can create your own help packages by using the same software and output type, then add those to the VTScada installation folder. To open your own topics from a page, you can add a SetHelp call to the Main state of that page, or write custom buttons for operators to select. (Other help authoring tools are unlikely to work.)

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
  • Tags have a field for a custom Help ID field but this will not open your documentation.
    Instead, add custom buttons to your page as described in these notes.

Process:

  1. Obtain a copy of Madcap Flare and use it to build your help project, with the output type set to HTML5.
    Name your output folder something like "CustomHelp" and copy it to the VTScada install folder (C:\VTScada\CustomHelp)
  2. 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. 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.

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

Deprecated Process:

The following methods continue to work but should not be used for new development.

You can add your own custom topics into your VTScada applications. With your own help file, you might choose to link pages or individual tag instances to topics in a custom CHM-format help file.

  • Link pages or individual tag instances to any of the 100 topic files that have been set aside in the VTScada help system for customer use. You may change the text in these files as required.
  • Link pages or individual tag instances to topics in a custom CHM-format help file.

Use the custom topic files, set aside for you 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.