3D PLM Enterprise Architecture

How to Activate the Contextual Help

During the execution of an interactive command, the corresponding contextual documentation can be made available by clicking on the F1 key. A page is then displayed in the browser explaining in detail the role of the command. Here is an example with the "Shaft" command :

Fig.1: Help text for the "Shaft" command

In order for the F1 key to enable the display of the help text page, it is necessary for the command to be the "focus", i.e., it must be either in exclusive or shared mode. See the "CAA Command Model" [1]  article for further explanations regarding the mode of a command.

Because of this limitation on the usage of the F1 key, there exists a second way of accessing the contextual documentation: by moving on the command the "What's This ?" command represented by the    icon. A "More Info" link has been added to the long help text. 

Fig.2: More Info

By clicking on it, a HTML page is displayed. Just above, it is an example with the "Reframe" command for which the F1 key cannot be activated. 

[Top]

Contextual Help Mechanism

On the one hand, there is a command and on the other a HTML page. The command is in a normal Framework containing code, whereas the HTML page is in a specific documentation file tree. The runtime link is established through a URL:

• The URL link is specified in the resources file associated to the command
• The address of the HTML page is associated to the URL through a mapping file

Therefore, by transition, starting from the command, it is possible to reach the documentation page.

The URL Link

The URL link for a command is an independant NLS resource. It can thus be found in the CATRsc files for the commands. The keyword used to associate a URL link is LongHelpId.

Example:

Let's have a look at an example based on the "Point" command for the CAAGeometry document used for command use cases. Here is an extract from the CAAAfrGeometryWksHeader.CATRsc file which is the resource file associated to the CATCommandHeader class for the " Point" command. This file is set in the CAAApplicationFrame.edu\CNext\resources\msgcatalog directory:

CAAAfrGeometryWksHeader.CAAAfrPointHdr.LongHelpId
                      = "CAAAfrGeometryWksHeader.CAAAfrPointHdr" ;

where:

For naming the URL link, follow the recommended rules for objects providing contextual help. For commands, see the "Creating Resources for Command Header" [2] technical article and for the Tools Options pages, see the "Application Property Access" [3] article.

The Mapping File

Contents of the Mapping File

The mapping file contains the equivalences between the URL links and the relative addresses of the HTML pages in the documentation file tree.

Example:

For the same "Point" command like just above, in the mapping file you have the following line:

CAAAfrGeometryWksHeader.CAAAfrPointHdr = "GeoWs/GeoWspoint.htm" ;

where:

Name of the Mapping file

The mapping file name is CommonId2url.CATNls.

Location of the Mapping File

The location of the mapping file in the documentation file tree is explained by the [Fig.5]

Multi-Documentation

For Dassault Systemes commands, the documentation can be found in an installation directory. Each DS partner has his own documentation file tree. This is why it is possible, at runtime, to concatenate the documentation file trees. Here is a screen shot of the Help tab page of the General option of the Options command. 

Fig.3: Concatenation of documentation path 

The order of concatenation is important: When searching for a page, the search goes from the first to the last path, ending as soon as the page has been found.

Note: The CATUserDocView variable is no longer available. 

[Top]

Contents of the Documentation File Tree

At runtime, a page associated to the command is created and displayed in the browser. This page has a frame set containing five sub-parts:

Fig.4: Organization of the created page

The information page:                 1	It is a HTML file which contains any information that can help the end user to better understand the command. Each file is located in a module, as explained in the [Fig.5].
The banner page of the current module:                 2	A module is a directory which groups together a set of information pages. The location of the modules directories in the documentation file tree is explained in the [Fig.5].   This banner page is a HTML page which contains information about the current module. The workbench name, its icon ... For a DS product line, the name of this banner file is depending on the module name and on the product line: <ModuleName><XXX>bnr.htm. <XXX> represents the product line group, it depends on the product line : The following table presents the corresponding product line group for each product line   :  Product Line Group Product Line CATIA CATIA_P3 CATIA_STUDENT CATIA_PLM_Express DELMIA DELMIA DELMIA_Automation DMU ENOVIA_3d_com ENOVIA_V5_VPM ENOVIA_DMU_Navigator ENOVIA_CES For a non DS product line, the name of this banner file is depending on the module name and on the product line name : <ModuleName><ProductLineName>bnr.htm. Refer to the  "What Is the Product Line Visual Identity" technical article [4], to find the name of the product line. This file is located in the same directory as the banner page of the product line. Refer to the fourth row of this table.
The table of contents page for the current module:                 3	It is a HTML file which contains links to the information pages found in the same module. There is only one table of contents file per module. For a DS product line, the name of this toc file is depending on the module name and on the product line: <ModuleName><XXX>toc.htm. Refer to the second row of this table to get values of line. <XXX> for each product line. For a non DS product line, the name of this toc file is depending on the module name and on the product line name : <ModuleName><ProductLineName>toc.htm. Refer to the  "What Is the Product Line Visual Identity" technical article [4], to find the name of the product line. This file is located in the module.
The banner page of the product line:                  4	It is a HTML file which contains links to pages that are not in the same module and especially a link to a home page that contains information regarding all of the modules. For a DS product line, the name of this banner file is depending on the product line: <XXX>bnr.htm. Refer to the second row of this table to get values of <XXX> for each product line. For a non DS product line, the name of this toc file is depending on the product line name : <ProductLineName>bnr.htm. Refer to the  "What Is the Product Line Visual Identity" technical article [4], to find the name of the product line. This banner file is, therefore, unique and is saved in a directory whose name depends on the product line: CATIAfr_C2 for CATIA_P3, catsfr_C2 for CATIA_STUDENT, xatfr_C2 for CATIA_PLM_Express,  DELMIAfr_D2 for DELMIA, wdafr_W2 for DELMIA_Automation, omdfr_O2 for ENOVIA_3d_com, lcafr_L2 for ENOVIA_V5_VPM, DMUfr_E2 for  ENOVIA_DMU_Navigator, vbafr_V2 for ENOVIA_CES, The name of the product line for a non DS product line [4] The location of this directory in the documentation file tree, is explained by the [Fig.5]
The navigation page:                  5	It is a HTML page which contains a navigation tool. this This file is located in a directory whose name depends on the product line: icons_C2 for CATIA_P3, CATIA_STUDENT and CATIA_PLM_Express,  icons_D2 for DELMIA and DELMIA_Automation.  icons_E2 for ENOVIA_3d_com, ENOVIA_V5_VPM, ENOVIA_DMU_Navigator and ENOVIA_CES icons_<ProductLineName> for non DS product line The location of this directory in the documentation file tree, is explained by the [Fig.5]

The architecture of the documentation file tree is the following:

Fig.5: Architecture of the Documentation File Tree 

The documentation file tree contains at the first level the online and resources directories for the English version, and a directory for each non English version. The non English version directory contains itself the  resources and online directories. The contents of these two sub-directories is the following:

• The resources sub-directory. 

This sub-directory always contains the msgcatalog directory. For the English version, this directory contains the mapping file, otherwise it contains a language directory containing the mapping file.

• The online sub-directory. 

For the English version, the online directory contains:

• modulei : each directory which represents a logical grouping for a workbench, a solution, a product, etc. It contains the documentation files for the commands and the table of contents file (toc). The online directory can have several modules. 

The names of these modules mustn't include the '_' character.

• image: The images used in the documentation files. 
• ProductLineName: the directory which contains the banner file of the product line and the banner of each module.
• icons_xxx : the directory which contains the no_navigation.htm file. 

For a non English version, between the online directory and all these above directories there is the language directory.

Refer you to the "Contextual Help for an Add-on" use case [6] for an example.

[Top]

In Short

This article has demonstrated how to create a documentation directory and described the mechanisms for a contextual help.

[Top]

References

History

Copyright © 2002, Dassault Systèmes. All rights reserved.