HTML5 CSH header file

[jonester]

I am creating an HTML5 help system and am trying to save the developer the headache of calling topics in the code for CSH. Is there a way for the technical writer to do all of the mapping? How do I include the dialog IDs in the header file? What is the format? Is there a sample header file available?

[Dave Lee]

Well, the code in your app that makes the CSH call to the help has to use an identifier - it has to send something to the help.

But you don't necessarily need to hard-code that identifier in the app.
For example, the app could automatically generate the identifier used in the CSH call.

That's what we do in our applications. It's a Windows app, and in Windows each form/screen has a unique name and "path" (namespace).
So when the app makes a CSH call, it generates the identifier from the form's unique name/path; e.g. MyApp_FeatureArea_FormName
It's then my job to add all those identifiers to my Flare alias file, and map them to appropriate topics.

The identifier doesn't have to be generated exactly like this, the key point here is that each identifier used for CSH must be unique, and it must be fixed and can't change.

If there's a lot of identifiers, the developer could make this job easier by writing an app that generates a list of all the possible identifiers for you, in a header file format. That will save time, and make sure you haven't missed any.

The developer might take some persuading, but it'll save them time in the long run. For any decent sized project, this will be quicker for them than manually adding identifiers in the code, or asking them to fix bugs in those identifiers.

[jonester]

Thanks, Dave. I understand the concept and have coded the mapping file for other output formats (such as HTML Help, WebHelp) many times. I just can't find an example of a full header file for HTML5. The only thing in the Flare documentation are the three elements that it generates: #define TOPICID NUMERICAL_IDENTIFIER. It doesn't include any identifier for the dialogs. I am authoring for a Windows 10 desktop program, and can get a list of dialog IDs from the developer. Is the mapping as simple as: #define TOPICID NUMERICAL_IDENTIFIER DIALOG_ID in the header file? Or is there another format?

[Dave Lee]

Thanks, Dave. I understand the concept and have coded the mapping file for other output formats (such as HTML Help, WebHelp) many times. I just can't find an example of a full header file for HTML5. The only thing in the Flare documentation are the three elements that is generates: #define TOPICID NUMERICAL_IDENTIFIER. It doesn't include any identifier for the dialogs. I am authoring for a Windows 10 desktop program, and can get a list of dialog IDs from the developer. Is the mapping as simple as: #define TOPICID NUMERICAL_IDENTIFIER DIALOG_ID in the header file? Or is there another format?

Perhaps go to the alias editor in Flare, create a few identifiers and map them to topics. Then look at the header (*.h) and alias (*.flali) files in a text editor, if you're interested in the file format.

* The header file (*.h) just contains those elements, i.e. #define <identifier> <value>
* The alias file (*.flali) is an XML file that contains the mappings between the identifier (or value) and the topic, e.g. <Map Name="identifier" Link="/Content/Topic.htm" />

[arkana]

So when the app makes a CSH call, it generates the identifier from the form's unique name/path; e.g. MyApp_FeatureArea_FormName
It's then my job to add all those identifiers to my Flare alias file, and map them to appropriate topics.

... the developer could make this job easier by writing an app that generates a list of all the possible identifiers for you, in a header file format.

Hi Dave, what's the process that you use to add the .h file the app creates to the Flare project? I'm hoping to find an automatic/seamless solution that doesn't involve copying and pasting etc. Can the App just copy the generated .h file to a specific folder within the Flare project, and Flare (and the alias file) will automatically recognize it?

[Nita Beck]

Can the App just copy the generated .h file to a specific folder within the Flare project, and Flare (and the alias file) will automatically recognize it?

The App can’t, but you can, and then Flare will indeed recognize it.

In Windows Explorer, navigate to your Flare project’s Project\Advanced folder (you might also prefer to add a sub folder called CSH) and drop the .h file in there. Next, open the Flare project and right-click on the Advanced folder (or CSH folder, if you added it) and select the command for adding a new alias file. When you open that alias file, Flare will indeed read the .h file to populate the alias file. (You might need to specifically select the .h file from a drop-down in the Alias editor’s toolbar.) You then must map Flare topics to the individual identifiers/IDs.

Sorry if I’ve kinda vague. I don’t have access to Flare at the moment.

HTH

[arkana]

Thanks Nita. Since our Flare project is bound to source control (we use TFS), in the same repository as the APP, I think we can have the APP create/maintain the header file in the Advanced folder of the Flare Project folder. The APP has access to all the directories in TFS. This is the automatic solution that I was after. So it seems that it is achievable, right?