CSH Clarification

[spatte22]

Hey there everybody,

I'm a fairly new Flare user trying to figure out context sensitive help, and I'd really appreciate it if someone could just make sure I'm on the right track and hopefully answer a few questions

Here is my general understanding of how to implement CSH with Flare:
I need to create alias and header files (header first). In the alias file, I can click the "generate identifiers for this project" icon to create a new identifier (ID) for each topic. After saving the new alias file, the header file(s) populates with all of the identifier "info" like the name and value. I also need to work with a developer to determine how we will implement a CSH "button" in the product applications for which we're providing Online Help - ie: a question mark/circle icon. After creating the identifiers, I give the developer the header(s) and a copy of the output files. Also, I work with the developer to identify which ID's correlate with their respective icons within the applications (if the automatically-generated ID names are not explicit enough), and then I suppose the developer implements them in the application? Do I need to do anything extra in Flare, as well? Lastly, since I work as part of a team, I will also create a standardized procedure guide for adding new CSH identifiers to the alias file as we add or change topics in the future.
Is that correct?



I also have a few additional questions, and again, any insight or advice would be immensely appreciated!

- if we change a topic title and prefer to have identifier names match topic titles, must we manually change the identifier name, too? how will this affect things from the developer's side, assuming we keep the value # the same?

- correct me if I'm wrong, but once the developer adds in the identifier info into an application, we can go into the alias file in Flare and assign the identifier to a different topic without breaking anything, right?

[NorthEast]

The identifier (or value) is important, since that's the key bit of information that connects your application to your help - the developer sends the identifier (or value) when they call the help.

I'd chat to your developer first to work out how you're going to set up the identifiers. You might generate them, or your developer might generate them.
Both you and your developer need to use these identifiers, so talk it though and find out what way would work best for both of you.

For example, in my projects the identifiers are created by the developer. When the app calls the help, the app generates the identifier on-the-fly based on the internal form name of that particular window/dialog, which is unique to that form. The key benefit of this is that identifiers don't need to be hard-coded in the application, which massively reduced the initial work for the developer, and eliminated maintenance for when we add new forms. The developer wrote a small tool that generates the list of identifiers in raw text, so I use that to create the header file, and then use that to create my alias file.

That might not work for you, but the important bit is to speak to the developer first before deciding how to go about this.

[spatte22]

When the app calls the help, the app generates the identifier on-the-fly based on the internal form name of that particular window/dialog, which is unique to that form. The key benefit of this is that identifiers don't need to be hard-coded in the application, which massively reduced the initial work for the developer, and eliminated maintenance for when we add new forms. The developer wrote a small tool that generates the list of identifiers in raw text, so I use that to create the header file, and then use that to create my alias file.

Oh, really?! Well that seems like it's backwards from my understanding... that the application generates a list of identifiers that I use, rather than me creating the identifiers. (Although, I realize that as I've been going through Flare's OH I've been following the instructions starting from me creating the identifiers rather than the developer)

I appreciate the response, man. As I used this forum's search function to find info on CSH, I saw your name/responses all over the place, so ya, thanks for being willing to help people
I suppose from here on out, like you suggested, I need to get everything going with a developer. I've recently taken on the project, so I'm trying to understand everything before I start setting up meetings with developers and whatnot.

[NorthEast]

When the app calls the help, the app generates the identifier on-the-fly based on the internal form name of that particular window/dialog, which is unique to that form. The key benefit of this is that identifiers don't need to be hard-coded in the application, which massively reduced the initial work for the developer, and eliminated maintenance for when we add new forms. The developer wrote a small tool that generates the list of identifiers in raw text, so I use that to create the header file, and then use that to create my alias file.

Oh, really?! Well that seems like it's backwards from my understanding... that the application generates a list of identifiers that I use, rather than me creating the identifiers. (Although, I realize that as I've been going through Flare's OH I've been following the instructions starting from me creating the identifiers rather than the developer)

Not really - we are still creating those identifiers and mapping them in Flare. All I wanted you to do was think about was how you go about creating the identifiers, as there may be more sensible options than just using Flare to auto generate them for you.

I could have created my own list of identifiers, then asked the developer to add those identifiers to the app for the help calls. But that's a lot of effort for the developer (we have about 2000 identifiers), and it means that any changes to identifiers (adding new identifiers, or correcting mistakes) require a code change in the app - something we really wanted to avoid.

So rather than do that, I asked the developer if there was anything that's already built-in to the app that we could re-use as an identifier for use in the help calls. Since it's a Windows app, each dialog/form in the app has an unique form name, so we could use that as an identifier when we make a help call. So if the form name was Product.Widget.Module.FormName, we could use that in the help and send the identifier Product_Widget_Module_FormName. The hard bit then was to create a list of all these identifiers and map them to topics in the Flare alias file, but that was work for me and not the developer. But it still halved the work overall, since the developer didn't have to hard-code thousands of identifiers in the app.

[TR Lisa]

So, in the scenario above, where we, the authors, use developer-provided unique identifiers, and map help topics to those, does the developer just need to drop in the header file and then configure the context-sensitive help button to call whatever help topic is mapped to the current page? Talking HTML5 output here.

I'm a little confused by this statement in the CSH guide, which makes it sound like dev still needs to link up each page individually, based on what they see in the header file:

Software Developer "Hooks" application interface or web links to online topics. The developer connects the dialogs, windows, or web links to the appropriate online topics using the information in the header file.

[Psider]

I think the "hook" probably means the bit of code that says "get the id and send it to the browser in xyz format". So they probably don't need to explicitly code the id, but will need to make sure that help call is available in the correct spots, e.g. add a ? icon in Widget1 and Widget2 and link it to the "OpenMyHelp" function, which automatically grabs the id, formats it correctly and send it to the browser. So if the application already exists, there will be some initial work to set it up (I'd imagine) but then should be mostly automatic from then on (assuming a form template which includes the mandatory code they need for each form). I'm not a dev, but that's my very basic understanding of one option.

(I'm sure Dave will jump in to correct any inaccuracies. :p )

[NorthEast]

So, in the scenario above, where we, the authors, use developer-provided unique identifiers, and map help topics to those, does the developer just need to drop in the header file and then configure the context-sensitive help button to call whatever help topic is mapped to the current page? Talking HTML5 output here.

No, there was no header file for the developer - the developer didn't need to add any of the identifiers to the app.
When you click help in the app, the app checks the internal name of that form (window, dialog box) such as Product.Widget.Module.FormName. It then makes a CSH call and generates the URL on-the-fly, using the form name as the identifier.

I had to set up the header and alias file in Flare, which was the harder bit. The developer wrote a tool to export a list of the form names, so I could use that as a starting point.

[TR Lisa]

I already have a list of page names in the app (around 300 unique identifiers) from Engineering. And I created a header and alias file with those page names in Flare. In the alias file, I mapped each page name to a help topic, as shown in the partial example below. In this example, how does the app know it should call the help topic mapped to ID 104 when the help button is clicked from the invoice profile co page? I know you've said "It then makes a CSH call and generates the URL on-the-fly" but I don't know what that means.

PAGE_INVDLG_INVPROFILE_CO Page_Invoicing_Profile_CO.htm /Content/PageHelp/ 104 TrackerPageHelpIdentifiers.h
PAGE_INVDLG_INVPROFILE_LF Page_Invoicing_Profile_LF.htm /Content/PageHelp/ 105 TrackerPageHelpIdentifiers.h

I've read the CSH guide front to back and front again and still this is not clear. I've got a ticket open with MadCap now to walk through this, but I think open discussion here also helps other authors. Thank you!

[devjoe]

There are several different ways that this whole architecture of app, help call, and context ID can be assembled. They are largely the same, but depending on the workflow in the specific software development tools, the exact steps may vary. In any case, something like one of the following happens:

1. Developer generates context IDs for help calls from the product and sends them (as a header file or otherwise) to writer.
2. Developer writes a function which handles help calls. For HTML5, this generates a URL and may do so by appending the ID to the base URL for context-sensitive help (something like "product.htm#cshid=" though this will generally have more of a path preceding it) which is stored in some program resource. For CHM this may be a library function which the developer simply calls, but even in this case, it is likely that the developer wraps it with a function which takes care of all the arguments which are constant for all help calls and just combines the ID with the rest.
3. Writer adds these IDs to help and links to appropriate help topics.
4. User requests help. The app calls the function to call help using the associated ID. For HTML5 help, this ultimately results in a URL like product.htm#cshid=123 being called.

1. Developer implements help calls using a unique string ID for each element and sends them to writer.
2. Developer writes help function (as above, but using the alias rather than the ID).
3. Writer adds these as aliases to help and links to appropriate topics. In this process, the numeric IDs are not needed.
4. User requests help. The app calls the function to call help using the associated alias. For HTML5 help, this ultimately results in a URL like product.htm#cshid=SOME_STRING_HERE being called.

1. Developer writes code without generating help IDs.
2. Developer writes help function (as above).
3. Writer writes help and generates IDs for each topic and sends header file to developer.
4. Developer links each code element to appropriate string or numeric ID.
5. User requests help. Function calls help with string or numeric ID. One of the two kinds of help calls mentioned above results.

After any of these processes:

1. The help system receives the help call using an alias or numeric ID.
2. If the numeric ID is used, the help system looks up the alias.
3. The help system calls the topic linked to the alias.
4. If any part of this fails (the ID doesn't exist, the alias doesn't exist or isn't linked to a help topic, or the topic doesn't exist), then, depending on the help system used and the point of failure, the user gets an error or the default help topic is shown.

[NorthEast]

I already have a list of page names in the app (around 300 unique identifiers) from Engineering. And I created a header and alias file with those page names in Flare. In the alias file, I mapped each page name to a help topic, as shown in the partial example below. In this example, how does the app know it should call the help topic mapped to ID 104 when the help button is clicked from the invoice profile co page? I know you've said "It then makes a CSH call and generates the URL on-the-fly" but I don't know what that means.

PAGE_INVDLG_INVPROFILE_CO Page_Invoicing_Profile_CO.htm /Content/PageHelp/ 104 TrackerPageHelpIdentifiers.h
PAGE_INVDLG_INVPROFILE_LF Page_Invoicing_Profile_LF.htm /Content/PageHelp/ 105 TrackerPageHelpIdentifiers.h

I've read the CSH guide front to back and front again and still this is not clear. I've got a ticket open with MadCap now to walk through this, but I think open discussion here also helps other authors. Thank you!

Well, you've done all of your bit in Flare - you've set up the alias file and linked your identifiers to the topics in your help. Remember to set your target to use the alias file too.
So you should be able to build your target output and test the CSH it yourself from Flare - Tools > Test CSH API Calls.

How does the app know it should call the help topic mapped to ID 104 when the help button is clicked from the invoice profile co page?

Your developers have to tell the app by implementing the help call - they can could do this using a simple URL or javascript as described here (URL is easiest):
https://help.madcapsoftware.com/flare20 ... -HTML5.htm

So for example, your app will make the CSH call and can send either the identifier "PAGE_INVDLG_INVPROFILE_CO" or the value "104" (I'd suggest sending the identifier as that's more meaningful).

[TR Lisa]

Ok so I think I misunderstood what you meant in a previous reply by "But it still halved the work overall, since the developer didn't have to hard-code thousands of identifiers in the app." I thought that meant dev didn't have to code the page help calls, and that the existing page identifier would read the header file and know what topic to call. So there is no way around dev having to initially hand code each page to the help topic. But the advantage is still that I can change a topic name or map a different topic to an identifier with no further dev effort required.

[NorthEast]

Ok so I think I misunderstood what you meant in a previous reply by "But it still halved the work overall, since the developer didn't have to hard-code thousands of identifiers in the app." I thought that meant dev didn't have to code the page help calls, and that the existing page identifier would read the header file and know what topic to call. So there is no way around dev having to initially hand code each page to the help topic. But the advantage is still that I can change a topic name or map a different topic to an identifier with no further dev effort required.

Yep, to do it manually, your developer would have to add the identifiers in the code, which could be pretty time consuming. That's why I mentioned what I did for the app where I work. I sat down and talked to the developers, and asked if there was anything that's already coded in the app that could be used as an identifier - i.e. some unique reference that's stored for each screen/window/dialog in the app. As it was a Windows app, each form already had a unique internal name, like Product.Widget.Module.FormName. So our developers didn't have to add thousands of new identifiers, they just had to send the internal form name as the identifier used in the CSH call. This solution works very well for us, as it saved the developers a lot of work, and we never need to add/change identifiers in the code or make code changes just for the help. All the work is all on my side, just adding identifiers and maintaining the alias file.