Click or drag to resize
Sandcastle Help File BuilderNamed URL Index Support

This topic contains the following sections.

The Named URL Index

The MS Help 2 system supports an index called NamedUrlIndex that makes it possible to customize some display aspects of a Help collection such as which page is displayed when a Help collection is first opened. Index terms are added to the data island within the page to specify the options. The most common ones are shown in the table below.

Index Term

Description

AboutPageIcon

The HTML file that displays the Help About image. See below for an example.

AboutPageInfo

The HTML file that displays product information in Help About. See below for an example.

DefaultPage

The page that appears when a user opens a help collection. This is often the same as the home page.

EmptyIndexTerm

The page that displays when a user chooses a keyword index term that has sub-keywords but is not directly associated with a topic itself.

FilterEditPage

Displays a page that can be used to edit help filters.

HomePage

The page that appears when a uses chooses the Home command or button.

NavFailPage

The page that opens if a link to a topic or URL is broken.

To add a term to a conceptual topic, create or open a content layout file and add the topic to it. In the properties for the topic in the layout file, edit the Index Keywords values. Select the NamedUrlIndex item as the index and enter one of the terms above in the value column. Add one entry for each term that you want to use.

Note Note

If you mark a conceptual topic as the default using the layout designer, the DefaultPage and HomePage keywords are added to the topic automatically at build time. As such, you do not need to specify them in the topic's keywords.

To add a term to an HTML file, add a data island to the page's <head> section if it does not already exist and add an <MSHelp:Keyword> entry with the Index attribute set to NamedUrlIndex and the Term attribute set to one of the index terms above. Specify one entry for each term that you want to use. For example:

HTML Page NamedUrlIndex Example
Copy
<head>
  <title>Welcome</title>
  <xml>
    <MSHelp:Keyword Index="K" Term="Welcome" />
    <MSHelp:Keyword Index="NamedUrlIndex" Term="HomePage" />
    <MSHelp:Keyword Index="NamedUrlIndex" Term="DefaultPage" />
  </xml>
</head>
AboutPageIcon and AboutPageInfo

These two terms are unique. Both are HTML pages but AboutPageIcon is used to display an image in the Document Explorer About box and AboutPageInfo is used to display product information in the Document Explorer About box. Below are examples of each.

AboutPageIcon.html
Copy
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
  <head>
    <meta HTTP-EQUIV="Content-Type" Content="text/html; charset=Windows-1252">
    <title>About My Product</title>
    <xml>
      <MSHelp:NoSearch />
      <MSHelp:Keyword Index="NamedUrlIndex" Term="AboutPageIcon" />
    </xml>
  </head>

  <body scroll="no" topmargin="0" rightmargin="0" bottommargin="0" leftmargin="0">
    <img src="Media/MyLogo.jpg" />
  </body>
</html>
AboutPageInfo.html
Copy
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html xmlns:MSHelp="http://msdn.microsoft.com/mshelp" DIR="LTR">
  <head>
    <meta HTTP-EQUIV="Content-Type" Content="text/html; charset=Windows-1252">
    <title>About My Product</title>
    <xml>
      <MSHelp:NoSearch />
      <MSHelp:Keyword Index="NamedUrlIndex" Term="AboutPageInfo" />
    </xml>
    <style type="text/css">
      body { font-family: Verdana; font-size: 65%; margin: 5px; width: 100%; }
    </style>
  </head>

  <body>
    <p/>Here is some info about My Product.
  </body>
</html>

The two HTML pages and the associated image file can be added as content items to the project (set the BuildAction on them to Content). The HTML files can be placed in any folder but if not placed in the root folder, adjust the URL to the image as needed. Set the ExcludeFromToc property to true on the HTML pages to ensure that they are excluded from the table of contents when the help file is built. The image should be placed in the .\Media folder.

You can also include the HTML pages using the content layout designer. If done this way, uncheck the Show in the table of contents option on the HTML pages so that they do not appear in the table of contents. If the image you use is also used in conceptual content, set the image's AlwaysCopy property to true so that it is always copied to the .\Media folder even if the reference in the conceptual content goes away or the page is not included in the layout.

See Also