Implementing Named URL Indexes
A named URL index 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.
Creating a Project-level Named URL Index
Creating a project-level named URL index is similar to creating other project-level keyword indexes: You include a named URL index (.HxK) file in your Help project, and then you add named URL keywords to XML data islands in HTML topic files, directly to the .HxK file, or a combination of both. The name of the .HxK file should then be associated with the !NamedUrlIndex moniker in the project's collection definition (.HxC) file.
The following table shows the named URL index keywords supported by Visual Studio and Microsoft Document Explorer.
Keyword |
Function |
|---|---|
AboutPageIcon |
HTML file that displays the Help About image. |
AboutPageInfo |
Displays product information in Help About. |
DefaultPage |
Appears when a user opens a Help collection. This is often the same as the home page. |
EmptyIndexTerm |
Displays when a user chooses a keyword index term that has subkeywords but is not directly associated with a topic itself. |
FilterEditPage |
Displays a page that can be used to edit Help filters. |
HomePage |
Opens when a uses chooses the Home command or button. |
NavFailPage |
Opens if a link to a topic or URL is broken. |
ProductID |
Displays the product ID in the Help About box. Microsoft Document Explorer looks for a value named PID under the specified HKEY_LOCAL_MACHINE registry key. |
RegisteredOrganization1 |
Displays the registered organization in the Help About box. Microsoft Document Explorer looks for a value named RegisteredOrganization under the specified HKEY_LOCAL_MACHINE registry key. |
RegisteredUser1 |
Displays the registered user in the Help About box. Microsoft Document Explorer looks for a value named UserName under the specified HKEY_LOCAL_MACHINE registry key. |
SampleDirPage |
The page that contains a directory of sample topics. Not exposed by Visual Studio or Microsoft Document Explorer, but available for use in scripting. |
Note
Any registry key will use the pseudo-protocol "ms-help-reg:" plus the full registry path for each entry, for example, <Keyword Term="RegisteredUser"><Jump Url="ms-help-reg://hklm/software/microsoft/msdn/8.0/help/0x0409/{1234ABCD-1234-ABCD-1234-ABCD1234ABCD}/registration">.
Creating a Collection-level Named URL Index
When a Help project is compiled, the named URL index keywords are combined with the keywords of the other project indexes. And just like the keywords in those other indexes, the named URL index keywords are not exposed at the collection level unless you create a collection-level named URL index (.HxK) file. The following example shows a typical collection-level named URL index:
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE HelpIndex>
<HelpIndex DTDVersion = "1.0"
Name="NamedUrlIndex"
Merge="Yes"
Sort="Yes"
Title="Named URL Index"
Visible="No"
LangId="1033">
</HelpIndex>
After you create the collection-level named URL index file, you must insert a reference to that .HxK file in the collection-level .HxC file. In addition, you must add an <ItemMoniker> element to the .HxC file that identifies the collection-level named URL index. The following example shows the .HxC entries required to expose a collection-level named URL index:
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE HelpCollection>
<HelpCollection DTDVersion="1.0" FileVersion="1.0.0.0" LangId="1033" Title="Help Integration Demo Collection" Copyright="Microsoft">
<AttributeDef File="HelpDemo.HxA" />
<TOCDef File="HelpDemo.HxT" />
<KeywordIndexDef File="HelpDemoKIndex.HxK" />
<KeywordIndexDef File="HelpDemoAIndex.HxK" />
<KeywordIndexDef File="HelpDemoFIndex.HxK" />
<KeywordIndexDef File="HelpDemoNamedUrls.HxK" />
<ItemMoniker
Name="!DefaultToc"
ProgId="HxDs.HxHierarchy" InitData="" />
<ItemMoniker
Name="!DefaultFullTextSearch"
ProgId="HxDs.HxFullTextSearch"
InitData="" />
<ItemMoniker
Name="!DefaultKeywordIndex"
ProgId="HxDs.HxIndex"
InitData="K" />
<ItemMoniker
Name="!DefaultAssociativeIndex"
ProgId="HxDs.HxIndex" InitData="A" />
<ItemMoniker
Name="!DefaultContextWindowIndex"
ProgId="HxDs.HxIndex"
InitData="F" />
<ItemMoniker
Name="!DefaultNamedUrlIndex"
ProgId="HxDs.HxIndex"
InitData="NamedUrlIndex" />
</HelpCollection>