Walkthrough: Creating and Building a New Help Topic
In this walkthrough, you will learn how to create a Help file that merges with the base Help that is provided by Microsoft. This lets you expand Microsoft Dynamics NAV Help to include content for your custom solution. You will also learn how to create Help calls to your new topics. In addition, you will learn a simplified way to create Help for new solution objects by replacing a standard Help call with a call to a new topic that describes a modified object and overrides the standard Help topic.
For information about how to base your Help project on existing source files and without creating a new Help project, see Walkthrough: Customizing an Existing Help Project.
About This Walkthrough
This walkthrough illustrates the following tasks:
Creating a new table, field, and page object in Microsoft Dynamics NAV.
Setting up the project folder structure.
Creating new topic files and adding the topics to the Help project by using HTML Help Workshop.
Exporting the object IDs and names from Microsoft Dynamics NAV.
Configuring and building a Help file by using Help Builder.
Integrating the new Help file together with the core Help and verifying that the new Help is called from the new and existing objects.
Note
This walkthrough focuses on how to create context-sensitive object reference Help. For information about how to write other types of topics, see Help Topic Types.
Prerequisites
To complete this walkthrough, you will need:
Microsoft Dynamics NAV 2013 R2 with a developer license.
The CRONUS International Ltd. demonstration database.
Microsoft Dynamics NAV Help Builder.
Microsoft Dynamics NAV Help Server.
HTML Help Workshop. For installation information, see Installation and Configuration (Microsoft Dynamics NAV Help Toolkit).
The example files from the Microsoft Dynamics NAV 2013 Help Toolkit.
An HTML editor. In this walkthrough, Notepad is the HTML editor that is used. When writing your Help, you can use a dedicated HTML Help authoring tool or you can use Word. For a list of tools, see HTML Editors.
Note
You can also enable Help debugging to expose Help call IDs. For more information, see How to: Enable Help Debug Mode.
Story
Simon is a Microsoft Certified Partner who has sold his solution, Direct Purchase Orders, to CRONUS International Ltd.. He wants to provide object reference Help that is called by using F1 or the Help buttons for the following three new objects and one existing object in his solution:
Direct Purchase Header table - object ID: T_50000
Linked Sales Order No. field - object ID: T_50000_1
Direct Purchase Orders page - object ID: N_50000
Customer Card page - object ID: N_21
Creating New Objects in the Database
To base the walkthrough on real objects, you will begin by making the three basic objects in the CRONUS International Ltd. demonstration database.
To create a new table with one field
In the Microsoft Dynamics NAV Development Environment, on the Tools menu, choose Object Designer.
In the Object Designer window, choose Table, and then choose the New button.
In the Field Name field, enter Linked Sales Order.
In the Data Type field, select Text.
Press Esc, and then choose the Yes button to save the table.
In the Save As window, enter 50000 in the ID field and Direct Purchase Header in the Name field.
Choose the OK button to save the table.
To create a new page with a control for the table field
In Object Designer, choose Page, and then choose the New button.
In the New Page window, enter 50000 in the Table field.
In the Page section, select Create blank page and Card, and then choose the OK button.
In the first line in Page Designer, enter Test in the Name field. This defines the required container.
In the second line, select Field in the Type field, and then choose the look-up button in the SourceExp field.
In the C/AL Symbol Menu window, select Rec, choose Linked Sales Order, and then choose the OK button.
Press Esc, and then choose the OK button to save the changes.
In the Save As window, enter 50000 in the ID field and Direct Purchase Order in the Name field.
Choose the OK button to save the new page.
Setting Up the Help Project
The Help project folders must follow a specific structure to enable Help Builder to process the files. Each project consists of a folder that uses the same name as the finished Help file. Each project folder must contain a Source subfolder that contains all project system files and source files that you are creating. After you compile the Help project for the first time, a subfolder named Processed is automatically created next to the Source subfolder to hold the built .chm file, under the Processed folder, you find the html folder, which holds all of the .html files.
In this walkthrough, you will call the new project addin_a and base it on the sample project folders provided with the Help toolkit installation. There are no restrictions on the naming of projects, so you can call the new project what you prefer.
To set up the example project
Create a folder named HelpExample on drive C of your computer.
Navigate to the Help Toolkit installation location, and then open the Samples folder. The installation is typically located at C:\Program Files\Microsoft Dynamics NAV 2013 Help Toolkit.
Copy the addin_a and Shared folders to C:\HelpExample.
The following illustration show how your example project should look.
.png "Folder structure for the example project")
Creating New Topics and Adding Them to the Help Project
To provide content to the user when she presses F1 from the new objects, you must create the topics and add them to a Help project file that will output the .html file. The naming of context-sensitive topics must follow a specific format to work.
If you are creating many new field topics under a table, then you can save time by using the Help Generator Tool. For more information, see Help Generator Tool. In this walkthrough, you will create four new topics and use Notepad to add content to the topic files.
Note
The authoring work that is involved in writing, linking, and organizing topics is not included. For information about different HTML editors for writing and organizing Help topics, see HTML Editors.
To create a Help topic for the new table
In Windows Explorer, open C:\HelpExample\addin_a\Source\html.
In the shortcut menu of T_9.htm, point to Open With, and then choose Notepad.
Find the <title> element and replace the text with the
($ T_50000 Direct Purchase Headers $)object token.Find the <span id="nsrTitle"> element and replace the text with the
($ T_50000 Direct Purchase Headers $)object token.On the File menu, choose the Save As button, and then enter T_50000.htm in the File Name field.
Choose the Save button, and then close Notepad.
To create a Help topic for the new field
In Windows Explorer, open C:\HelpExample\addin_a\Source\html.
In the shortcut menu of T_9_1.htm, point to Open With, and then choose Notepad.
Find the <title> element and replace the text with the
($ T_50000_1 Linked Sales Order $)object token.Find the <span id="nsrTitle"> element and replace the text with the
($ T_50000_1 Linked Sales Order $)object token.On the File menu, choose Save As, and then enter T_50000_1.htm in the File Name field.
Choose the Save button, and then close Notepad.
Note
The F1 Help call for field topics is established by the object ID string T_50000_1 because the Linked Sales Order field is field 1 in table 50000 in Microsoft Dynamics NAV. If you change this naming, the context-sensitive Help will no longer work.
To create a Help topic for the new page
In Windows Explorer, open C:\HelpExample\addin_a\Source\html.
In the shortcut menu of N_10.htm, point to Open With, and then choose Notepad.
Find the <title> element and replace the text with the
($ N_50000 Direct Purchase Orders $)object token.Find the <span id="nsrTitle"> element and replace the text with the
($ N_50000 Direct Purchase Orders $)object token.On the File menu, choose the Save As button, and then enter N_50000.htm in the File Name field.
Choose the Save button and close Notepad.
To create a Help topic for the new Customer Card page
In Windows Explorer, open C:\HelpExample\addin_a\Source\html.
In the shortcut menu of N_10.htm, point to Open With, and then choose Notepad.
Find the <title> element and replace the text with the
($ N_21 Customer Card $)object token.Find the <span id="nsrTitle"> element and replace the text with the
($ N_21 Customer Card $)object token.On the File menu, choose the Save As button, and then enter N_21.htm in the File Name field.
Choose the Save button, and then close Notepad.
Note
The last topic has the same object token as the existing standard Customer Card Help topic. In a later procedure, you will assign a new priority value to your new Help project. The Help call will override the existing standard topic and call this new topic instead.
After you have created the new topic files, add them to the Help project by using HTML Help Workshop.
To add new topics to the Help project file by using HTML Help Workshop
On the taskbar, choose Start, choose All Programs, and then choose HTML Help Workshop.
On the File menu, choose Open.
In the File name field, type C:\HelpExample\addin_a\Source\addin_a.hhp, and then choose Open.
On the Project tab in HTML Help Workshop, choose the Add/remove topic files button.
In the Topic Files window, choose Add, and then select the new and changed files; N_21, N_50000, T_50000_1.
On the File menu, choose Save Project.
Note
The tasks of creating, adding, and organizing topics in a Help project can be performed more efficiently in a dedicated HTML Help editor, such as Adobe RoboHelp, if you still want to generate .chm files for internal purposes.
Warning
You can also use HTML Help Workshop to remove existing HTML files that were part of the Samples project in the Help Toolkit package; in this case N_10.htm, R_9.htm, T_9.htm, and the corresponding fields for T_9.htm.
Creating the Object String File
After you have created the new topics and added them to the new Help file, you can export the object names and IDs from Microsoft Dynamics NAV. These object names and IDs will be used by Help Builder to establish the Help calls.
Note
You only have to export object names and IDs for which you are creating new Help topics. For this walkthrough, you only have to export the three new objects. The following steps describe how to export names and IDs for all objects.
To export object names and IDs from Microsoft Dynamics NAV
Open Microsoft Dynamics NAV Development Environment with Microsoft SQL Server.
On the Tools menu, choose Object Designer, and then choose All.
On the Edit menu, choose Select All.
On the Tools menu, point to Translate, and then choose Export.
In the File name field, type C:\HelpExample\object.txt, and then choose the Save button.
After you have exported the object names and IDs, you can use the object file as input to the Help Builder after you have converted it to an object.xml file. For more information, see How to: Create the Object String File.
Building the Help Files
After you have created the new content and the object string file, which you have converted to object.xml, build the Help file by using Help Builder.
If you are building translated content, then you should use the configuration settings that installed with the Help Toolkit at My Documents\Microsoft Dynamics NAV 2013 Help Toolkit\Config\Help Builder\[locale].
Important
Before you build your Help using the Microsoft Dynamics NAV 2013 Help Toolkit, you must modify the configuration files for Help Builder to not include the navigation elements in hyperlinks between topics. For more information, see Upgrading Your Existing Help Content.
To build the Help files
Choose Start, point to All Programs, choose Microsoft Dynamics NAV 2013 Help Toolkit, and then choose Microsoft Dynamics NAV Help Builder.
Step through the Help Builder Wizard, specifying the Help project to compile, the configuration file to use, the object string file to use, and the output file. For more information, see Help Builder Wizard.
The log should contain no errors. The folder at C:\HelpExample\addin_a\Processed\ should contain the .chm file, which is addin_a.chm. Go to the C:\HelpExample\addin_a\Processed\html to find the generated .html files, these are the files that you will deploy to your Help Server.
For information about resolving potential Help build errors, see Troubleshooting Help Errors.
Integrating and Verifying the Help File with Core Help
After you have built the new Help files, the final steps are to integrate the new content with the core Help and to verify the change in Microsoft Dynamics NAV.
To integrate the new Help with Microsoft Dynamics NAV Help
In Windows Explorer, open C:\HelpExample\addin_a\Processed\html.
In Windows Explorer, copy all of the generated HTML files to your equivalent of C:\inetpub\wwwroot\DynamicsNAV71Help\en.
To view the new page and field Help in Microsoft Dynamics NAV
Start the client.
In the Search box, enter Direct Purchase Orders, and choose the related link.
Select the Linked Sales Order field, and then press F1.
This opens a browser window with your Microsoft Dynamics NAV Help Server, and your new topic displays.
Non-Object Reference Help
In addition to the reference topics created earlier in this walkthrough, you should also create process-oriented topics. You should link these task or business process topics to your window topics, or make them context-sensitive by applying object tokens. For key topics that explain your application functionality, consider adding them in the ToC.xml file. For an overview of different topic types and their characteristics, see Writing Help.
See Also
Tasks
Walkthrough: Customizing an Existing Help Project
How to: Change Language Settings for Local Content
How to: Enable Help Debug Mode
Concepts
Installation and Configuration (Microsoft Dynamics NAV Help Toolkit)
Writing Help
Building Help
HTML Editors