Walkthrough: Adding Custom Help to an Enterprise Template
This walkthrough shows how to add your own help topics to the Enterprise Template you provide to your development team. You make these help topics available to the development team through the Dynamic Help window in the Visual Studio integrated development environment (IDE).
Before You Begin
In the Visual Studio New Project dialog box, the Enterprise Templates folder contains icons that represent different types of projects. You can add your own custom Enterprise Template, complete with policy, to the choices offered in this dialog box by following the steps of Walkthrough: Creating a New Enterprise Template. You can also add custom help topics that can be read by developers working on projects based on that Enterprise Template.
Some of the projects represented by the Enterprise Templates contain a node called WinUI. This walkthrough shows how to create a custom help topic that appears in the Dynamic Help window when the WinUI node is selected in Solution Explorer.
Process for Adding Custom Help
Your template can include help topics to provide the guidance the development team needs in addition to the customization you incorporate into the template and programming environment through your policy file. For this walkthrough, you can use any document or URL you choose to display your topics, but the walkthrough begins by suggesting an HTML document to illustrate what you should see when you have finished.
The process for this walkthrough consists of the following:
- Preparing the help topic (an HTML file). This topic is used for illustrative purposes only, so it can contain any HTML content.
- Setting up a Dynamic Help topic category for the new topic. A Dynamic Help topic category is an area of the Dynamic Help window in which related help topics are grouped together.
- Setting up Context Keywords that point to the help topic.
- Associating a Project and an ELEMENT node with particular keywords.
Preparing the Help Topic
To create a sample help topic for a development team
- In Windows Explorer, navigate to your C: drive and create a new folder named Guidance.
- Create a file in the Guidance folder and name it CustomWinUI.htm. Type or paste any valid HTML content in the file, then save and close it.
Setting Up Dynamic Help Topic Categories
When you select the WinUI node in Solution Explorer, Visual Studio-provided help topics display in the Dynamic Help window. You could add your custom help topics to that list, but to help your development team find the custom topics, you can define a new topic category that provides a separate section for them in the Dynamic Help window.
To define a custom topic category
- In Windows Explorer, open the following folder:
C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\IDE\HTML\XMLLinks\1033
Tip The folder name 1033 is the codepage/language code ID (LCID).
- In this folder, create a new text file and name it CustomHelp.xml. This file is known as a context file.
- In this new file, add the following:
<?xml version='1.0' encoding="utf-8" ?> <DynamicHelp xmlns="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd"> <LinkGroup ID="customhelp" Title="Custom Help Topics" Priority="2"> <Glyph Expanded="vs:/ctxmsc_show.gif" Collapsed="vs:/ctxmsc_hide.gif/" /> </LinkGroup> </DynamicHelp>
In the LinkGroup node, the ID attribute specifies an identifier for this new topic category that you use when you add the Context node to the CustomHelp.xml file to associate content with a particular group (see the Setting Up the Context Keywords section below). The Title attribute specifies the name of the topic category to display in the Dynamic Help window. The Priority defines the relative priority of this topic category compared with other topic categories in the Dynamic Help window. The Glyph node specifies the icon to display with the topic category name. You can create your own icon, but this walkthrough uses the standard Visual Studio icon used for the Miscellaneous section. You can see several other icon choices by navigating to the ...\1033 folder described in step one above and opening the context.xml file.
Setting Up the Context Keywords
In the CustomHelp.xml file you need to define an action to be associated with one or more keywords. Typically, this action is to display an HTML file or an HTML Help topic. For this walkthrough, this means displaying the help file you created and named CustomWinUI.htm.
To associate a topic with an action
- In the CustomHelp.xml file, insert the content shown below in bold after the
</LinkGroup> <Context> <Keywords> <KItem Name="WinUI" /> <KItem Name="VBC" /> <KItem Name="Policy" /> </Keywords> <Links> <LItem URL="c:\Guidance\CustomWinUI.htm" LinkGroup="customhelp"> WinUI Development Notes </LItem> </Links> </Context>
The Keywords node contains the KItem keywords that cause this topic to display. The Links node specifies the location and name of the custom help file, as well as the section of the Dynamic Help window in which the topic should appear. In this case, it points to a new topic category, but an existing topic category (Help, Getting Started, Samples, and so on) could also be used.
Note In this case you do not need an Attributes node. For more information, see the Attributes Node subheading in Custom Context Files and Displaying Help Topics.
Associating an ELEMENT with Keywords (KItems)
The next step is to associate the custom help file you created with the applicable ELEMENT in your policy file. First, make a custom copy of the standard policy file (DAP.tdl) and then modify the copy. This leaves the original DAP.tdl file unchanged for future use.
To create a custom version of DAP.tdl
- In Visual Studio from the File menu, point to Open, and click File. The Open File dialog box appears.
- Navigate to the policy folder. If you chose the default installation location, the policy folder is C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy.
- Select the DAP.tdl file and copy it. To do this, either press Ctrl+C or right-click the file and select Copy.
- Paste a copy of the DAP.tdl into the same folder by either pressing Ctrl-V or right-clicking in an open area of the folder and selecting the Paste option. A copy of the file appears with the other .tdl files.
- Right-click the copy you just made ("Copy of DAP.tdl") and rename it MyDAP.tdl.
To modify the MyDAP.tdl file
- Double-click MyDAP.tdl to open it in the Visual Studio XML Designer. Editing this file in the Visual Studio IDE provides the convenience of syntax coloring and tag completion.
- Find the ELEMENT definition for the WinUI project by searching for
- Following the <ID>projWinUI</ID> line, but before the opening <IDENTIFIERS> tag, edit the CONTEXT node so that it appears as noted below in bold:
<ID>projWinUI</ID> <CONTEXT> <CTXTKEYWORD>WinUI</CTXTKEYWORD> <CTXTKEYWORD>VBC</CTXTKEYWORD> <CTXTKEYWORD>Policy</CTXTKEYWORD> </CONTEXT> <IDENTIFIERS>
The three entries WinUI, VBC, and Policy correspond to the three keywords you inserted into the context file (CustomHelp.xml) associated with your new topic.
- Save your changes and close MyDAP.tdl.
Associating the New Policy File with Your Project
Now you can associate the newly edited policy file (MyDAP.tdl) with a project and verify that you changed the IDE of Visual Studio .NET as expected.
To associate a policy file with a project
- Open Visual Studio .NET.
- Create and save a new Visual C# Distributed Application. Name it, for example, Project2.
- In Solution Explorer, right-click the top-level project in your solution (Project2), and click Properties.
- In the Properties window, click the Policy File property and then click the ellipsis button (...).
The Select a TDL File dialog box appears.
- In the Select a TDL File dialog box, double-click the file MyDAP.tdl. This changes the value of the Policy File property to MyDAP.tdl.
- Choose Yes when prompted to close and re-open your project.
To check the results
- In Solution Explorer, select the WinUI project and view the Dynamic Help window. (By default, it is tab linked with the Properties window. If you do not see it, from the Help menu, click Dynamic Help.)
- Click your new custom help topic (in this case called WinUI Development Notes) to see the following:
To add additional help topics, repeat this process, defining additional Context entries with keyword sets and related topics, associating each to a particular ELEMENT in your policy file. If you subsequently make changes to your context file, you must restart Visual Studio for the changes to appear.