Click or drag to resize

Editing Template Pages

Nimbus generates the driver help file by taking content entered via the Help Editor for a particular item (such as a method or property) and inserting it into the help template page for that item type. Each type of page generated by Nimbus has an HTML template file associated with it in one of the subfolders of Template\Html folder. This topic explains how the help template can be edited to control how Nimbus renders specific types of help pages.

Note Note

Editing the help template HTML files affects all pages of that type. For instance, editing the template page for IVI.NET methods (IviNetMethod.html) affects how the pages for all IVI.NET methods in the driver are rendered.

Understanding Help Template Pages
Note Note

The discussion below uses examples from IVI.NET drivers, but the procedures and techniques are very similar for IVI-COM and IVI-C drivers.

Since the help template contains both fixed HTML content intermixed with auto-generated content, the help template pages will contain replacement tags (identifiers enclosed in "$$") embedded in the HTML content. Also, note that since the help template resource file is an XML file, all of the HTML tags must be "escaped".

Important note Important

Even though help template pages have an extension of .html, the contents of those files must be XHTML. Among other things, this means that all HTML tags must be closed just like XML tags are. For example, instead of using <hr> to insert a horizontal separator, you must use <hr/> or <hr></hr>. If any XHTML rules are violated, the driver help previewer will display an error, and the help project will fail to build.

Help template files are required to be XHTML in order to be used by the Microsoft Help Viewer.

The following is help template page (IviNetMethod.html) used to generate IVI.NET methods. The template page is located under Template\Html\IviNetMethod.

XML
Copy
    <html xmlns:MSHelp="http://msdn.microsoft.com/mshelp" xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:msxsl="urn:schemas-microsoft-com:xslt">
  <head>
    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8" />
    <META NAME="save" CONTENT="history" />
    <title>$$METHOD_NAME$$ Method</title>
$$STYLESHEET$$
    <xml>
      <MSHelp:TOCTitle Title="$$METHOD_NAME$$ Method " />
      <MSHelp:RLTitle Title="$$PARENT_NAME$$.$$METHOD_NAME$$ Method  ($$NAMESPACE_NAME$$)" />
      <MSHelp:Keyword Index="A" Term="M:$$NAMESPACE_NAME$$.$$PARENT_NAME$$.$$METHOD_NAME$$" />
      <MSHelp:Keyword Index="K" Term="$$METHOD_NAME$$ method" />
      <MSHelp:Keyword Index="K" Term="$$PARENT_NAME$$.$$METHOD_NAME$$ method" />
      <MSHelp:Keyword Index="F" Term="$$METHOD_NAME$$" />
      <MSHelp:Keyword Index="F" Term="$$PARENT_NAME$$.$$METHOD_NAME$$" />
      <MSHelp:Keyword Index="F" Term="$$NAMESPACE_NAME$$.$$PARENT_NAME$$.$$METHOD_NAME$$" />
$$METHOD_INDEX_VALUES$$
      <MSHelp:Attr Name="DocSet" Value="$$DOCSET$$" />
      <MSHelp:Attr Name="DevLang" Value="VB" />
      <MSHelp:Attr Name="DevLang" Value="CSharp" />
      <MSHelp:Attr Name="DevLang" Value="C++" />
      <MSHelp:Attr Name="Locale" Value="en-us" />
      <MSHelp:Attr Name="TopicType" Value="kbSyntax" />
      <MSHelp:Attr Name="TopicType" Value="apiref" />
      <MSHelp:Attr Name="Abstract" Value="$$METHOD_SUMMARY$$" />
    </xml>
    <!-- begin: Microsoft Help 1.0 -->
    <meta name="Microsoft.Help.Id" content="" />
    <meta name="Microsoft.Help.TocParent" content="" />
    <meta name="Microsoft.Help.TocOrder" content="" />
    <meta name="Microsoft.Help.ContentType" content="" />
    <meta name="Microsoft.Help.SelfBranded" content="true" />
    <meta name="Microsoft.Help.Locale" content="en-us" />
    <meta name="Microsoft.Help.TopicLocale" content="en-us" />
    <!--$$Microsoft.Help.F1$$-->
    <!--$$Microsoft.Help.Keywords$$-->
    <!-- end: Microsoft Help 1.0 -->
  </head>
  <body>
    <input type="hidden" id="userDataCache" class="userDataStyle" />
    <input type="hidden" id="hiddenScrollOffset" />
    <div id="header">
      <table id="topTable" cellpadding="0" cellspacing="0">
        <tr>
          <td colspan="2" height="10">&nbsp;</td>
        </tr>
        <tr id="headerTableRow1">
          <td align="left">
            <span id="runningHeaderText">$$RUNNING_HEAD$$</span>
          </td>
          <td align="right">
            <span id="nimbusHeaderText">$$NIMBUS_HEADER$$</span>
          </td>
        </tr>
        <tr>
          <td colspan="2" height="10">&nbsp;</td>
        </tr>
        <tr id="headerTableRow2">
          <td align="left">
            <span id="nsrTitle">$$PARENT_NAME$$<span class="cs">.</span><span class="vb">.</span><span class="cpp">::</span><span class="nu">.</span>$$METHOD_NAME$$ Method </span>
          </td>
        </tr>
        <tr id="headerTableRow3">
          <td align="left">
          <a href="$$PARENT_LINK$$">$$PARENT_NAME$$</a>  <a href="#seeAlsoToggle" onclick="OpenSection(seeAlsoToggle)">See Also</a>  <span id="headfb" class="feedbackhead" /></td>
        </tr>
      </table>
      <table id="gradientTable">
        <tr>
          <td class="nsrBottom" background="../icons/gradient.gif" />
        </tr>
      </table>
    </div>


    <!-- Main section (everything below first separator line) -->
    <div id="mainSection">

      <!-- Main body (between header separator line and footer separator line) -->
      <div id="mainBody">
        <div id="allHistory" class="saveHistory" onsave="saveAll()" onload="loadAll()">
        <font color="DarkGray"></font>
        <p />
        </div>

        <!-- Summary -->
        <div class="summary">
          <p>$$METHOD_SUMMARY$$</p>
        </div>
        <p />
        <b>Namespace:</b>
        $$NAMESPACE_NAME$$<br/>
        <b>Assembly:</b>
        <a href="$$ASSEMBLY_LINK$$" tabindex="0">$$ASSEMBLY_NAME$$</a> (in $$ASSEMBLY_FILE_NAME$$)
   
        <!-- Syntax -->
        <h1 class="heading"><span onclick="ExpandCollapse(syntaxToggle)" style="cursor:default;" onkeypress="ExpandCollapse_CheckKey(syntaxToggle, event)" tabindex="0">
          <img id="syntaxToggle" onload="OnLoadImage(event)" class="toggle" name="toggleSwitch" src="../icons/collapse_all.gif" />Syntax</span>
        </h1>
        <div id="syntaxSection" class="section" name="collapseableSection" style="">
          <div id="syntaxCodeBlocks" class="code">
$$METHOD_SYNTAX$$
          </div>

$$TYPE_PARAMETER_DESCRIPTIONS$$

$$METHOD_PARAMETER_DESCRIPTIONS$$

$$METHOD_RETURNS$$
        </div>

$$CustomField.IviNetMethod.Remarks$$

$$METHOD_COMMANDS$$

$$METHOD_REQUIREMENTS$$

        <!-- See also -->
        <h1 class="heading">
          <span onclick="ExpandCollapse(seeAlsoToggle)" style="cursor:default;" onkeypress="ExpandCollapse_CheckKey(seeAlsoToggle, event)" tabindex="0">
          <img id="seeAlsoToggle" onload="OnLoadImage(event)" class="toggle" name="toggleSwitch" src="../icons/collapse_all.gif" />See Also</span>
        </h1>
        <div id="seeAlsoSection" class="section" name="collapseableSection" style="">
          <h4 class="subHeading">Reference</h4>
          <div class="seeAlsoStyle"><a href="$$PARENT_LINK$$">$$PARENT_NAME$$ $$PARENT_TYPE_KIND$$</a></div>
          <div class="seeAlsoStyle"><a href="$$ASSEMBLY_LINK$$" tabindex="0">$$ASSEMBLY_NAME$$ Assembly</a></div>
        </div>

      </div>

$$FOOTER$$

    </div>
  </body>
</html>

The content of the help template can be edited to include any arbitrary HTML, as long as you adhere to the more stringent formatting requirements for XHTML mentiond above. This can be used to implement custom branding or any other desired appearance affect or to inject custom content into all pages of a particular type.

Replacement Tags in Help Template Pages

The help template page contains two types of replacement tags (enclosed in "$$"). The find kind of tag that can be used in a help template page are custom fields. These all begin with $$CustomField and allow you to inject variable, developer-specified help content into a help page. Custom fields are discussed in the next section.

The second kind of replacement tags are those that appear in all capital letters, such as $$METHOD_SYNTAX$$. These tags are automatically replaced by Nimbus-generated content. For example, the $$METHOD_SYNTAX$$ tag is replaced by the Nimbus-generated method signature. The driver developer does not explicitly enter the content for these tags in any editor. Rather, Nimbus infers this content from other information in the driver.

In many cases, the Nimbus-generated replacement tags are formatted using other HTML pages in one of the subfolders of the Template\Html folder. Editing these "child" template pages entries provides fine-grained control over the help page formatting and content. For example, the following is the template file for the "Return Value" section of the IVI.NET method help template page. Note that the name of these template files of help template pages all begin with the name of the "parent" page ("IviNetMethod.html" in the example below).

XML
Copy
<!-- Html\IviNetMethod\IviNetMethod.Returns.html -->

<!-- Return value -->
<h4 class="subHeading">
    Return Value</h4>
<br />
<p>
    $$RETURNS$$</p>
Adding Content with Custom Fields

The help template pages include special replacement tags known as custom fields. These specially named tags are replaced by content that the driver developer enters for that field in the Help Editors. Custom fields have names in the following form:

CustomField.<pageType>.<fieldName>.html

For IVI.NET drivers, <pageType> can be replaced with any of the following values:

  • IviNetAssembly

  • IviNetClass

  • IviNetConstructor

  • IviNetDelegate

  • IviNetEnum

  • IviNetEvent

  • IviNetInterface

  • IviNetMethod

  • IviNetProperty

  • IviNetStruct

For IVI-COM drivers, <pageType> can be replaced with any of the following values:

  • IviComMethod

  • IviComProperty

  • IviComInterface

  • IviComEnum

  • IviComClass

  • IviComNamespace

  • IviCFunction

  • IviCAttribute

For IVI-C drivers, <pageType> can be replaced with any of the following values:

  • IviCFunction

  • IviCAttribute

When a custom field is defined, Nimbus does two things:

  1. It updates the help editor for the pageType specified so that an editable field called fieldName appears.

  2. When the help project is built, it replaces all occurrences of custom field replacement tags with the help editor content entered for those custom fields.

Tip Tip

Nimbus actually uses custom fields for some of the standard sections of help pages. For instance, the Remarks and Units sections that appear on many help pages are implemented using custom fields. Searching the various help template files for instances of "CustomField" will yield numerous examples of how custom fields can be defined and used in help template pages.

To add a custom field to a help template page

  1. Add a new HTML file to one of the subfolders of the Html\Templates folder of the driver help project. Be sure to name the file using the desired page type and the desired field name as you want it to appear in the help editor. For example, the HTML file for the pre-defined Remarks custom field for IVI.NET property pages is named "CustomField.IviNetProperty.Remarks". The contents of this file are as follows:

    XML
    Copy
    <!-- \Html\IviNetProperty\CustomField.IviNetProperty.Remarks.html -->

<!-- Remarks -->
<h1 class="heading">
    <span onclick="ExpandCollapse(remarksToggle)" style="cursor: default;" onkeypress="ExpandCollapse_CheckKey(remarksToggle, event)"
        tabindex="0">
        <img id="remarksToggle" onload="OnLoadImage(event)" class="toggle" name="toggleSwitch"
            src="../icons/collapse_all.gif" />Remarks</span>
</h1>
<div id="remarksSection" class="section" name="collapseableSection" style="">
    <p>
        $$CUSTOM_FIELD_VALUE$$</p>
</div>

  2. Add any desired fixed HTML content inside the new template page.

  3. Place the $$CUSTOM_FIELD_VALUE$$ tag within the HTML content at the location where you want the content from the help editor to be inserted. Note in the example above that the $$CUSTOM_FIELD_VALUE$$ tag is embedded in a <div> tag that appears after <span> and <img> tags.

  4. Insert the replacement tag for the custom field (e.g. the custom field name enclosed in "$$") at the desired location in the appropriate help template page. For example, the pre-defined Remarks custom field appears within the help template property page as shown below (the entire help template page is not shown):

    XML
    Copy
    <!-- Template\Html\IviNetProperty\IviNetProperty.html -->

<!-- ... -->

$$PROPERTY_PARAMETER_DESCRIPTIONS$$

          <h4 class="subHeading">Property Value</h4>
          <p>$$PROPERTY_SUMMARY$$</p>
        </div>

$$CustomField.IviNetProperty.Remarks$$

<!-- ... -->
See Also

Download a complete CHM version of this documentation here.