MadCap Software Forums

Our application is written in C# and our developers are having trouble implementing context-sensitive help based on Map IDs I've generated. Is anyone here using CS help with an application written in C#? How are you doing it? I'm hoping to come up with an easy way to manage this. Right now, they are doing it all manually. I have version 10.2.2 of Flare.

Thanks, Donna

Hi Donna,

What output type are you publishing from Flare? From the developer's perspective, the method of calling the page using the CSHID differs per output type.

As a starting point, if you enter "CSH" into the Flare search, the first 10 or so topics listed are specifically the steps that the developer needs to do to implement the CSHID calls.

The information mentioned above is also available in the following PDF document:
http://docs.madcapsoftware.com/FlareV10 ... HGuide.pdf

If you're referring to the challenge of communicating to developers which screen gets which ID, sorry to say that I couldn't find an easy way to manage it. Just grunt work. But I got it done for 900+ screens. My approach was to manually build a detailed spreadsheet that listed every screen name and its associated help topic and help ID. It was a massive pain to create, but the developers loved it. They were able to add all the context IDs in one fell swoop, quickly and with few errors. I received compliments along the lines of, "We need more developers around here who take the time to create such detailed technical notes." I keep the spreadsheet current whenever a new screen is added, and, now that the grunt work is done, it is really nice to have it as a reference.

Yes, I also have a similar problem. Our devs have hardcoded the .html filenames in their code, so if I happen to change a topic filename, the help breaks. It's a massive PITA, so I'd love to find some way to persuade them to use IDs rather than hardcoded filenames. (I wanted to change filenames so that I could implement some kind of file naming convention, or so that when the help structure changes I can then move topics into different sub-folders.)

For a new project I prefixed all topic filenames with CSH_, which highlighted to me that I couldn't change that filename without pain, but it's less than ideal.

Dandam, surely the alias file in Flare is the same as keeping a spreadsheet? And do your devs use helpIDs rather than the topic filenames? Even if your help doesn't USE the file generated by Flare, that might be a helpful way to keep your list of topics used in help current, so you don't have to do it outside of Flare. (Just a thought, I could be wrong!)

We use HelpID values. The alias file doesn't include a listing of the screen names found in the C# .NET application. The topic names and aliases in the alias file resemble the screen names, but they aren't exact enough to be a reliable guide for the developers, especially given that many of the screens have maddeningly similar names. So my spreadsheet lists the precise screen names so the developers don't have to think or interpret anything--they just insert the right number with the right screen.

But you can add those screen names in the alias file. It was just a suggestion, if you wanted to keep your list of topics all visible from within Flare. Here's a little extract from one of the alias files in one of our projects (which does use identifiers): You can see that the identifiers match the topic names exactly for the first two, but the second two are different.

Just a thought. (Wish I could get all our devs to work like this...)

Yes, I made a judgement call early on that may have added unnecessary work for me--but the developers appreciated it.

I couldn't create Aliases with the exact same name as the screens because many screens have identical names but reside on different nodes on the tree hierarchy, and thus require unique topics. But, yes, with the Aliases alone, the developers could have figured it out. But it would have required extra cognitive effort from the developers to do so. Never a good idea . Here is an example from my spreadsheet:
But that's all in hindsight. I started this project at least a year (a year!) before the developers got around to figuring out how to implement CS help, so I had to cover my bases from the beginning. There was no way to know what approach would work best, so I just gritted my teeth from the outset and chose a route that assured success--even if it required extra leg-work on my end.

The approach we took was not to hard code any IDs/values in the application itself.

The identifiers that are used in the CSH calls are automatically generated by the app, based on the internal form name (in the C# app), using the full namespace of the form so that they're unique.
For example, if the full form name was app.module.name, then the app would make a CSH call to Default.htm#cshid=app_module_name (substituting '.' with '_' to make it a valid identifier name).

The big advantage of this is that because you don't include any identifiers in the application code, you never need to change the code - everything can be managed from the alias file.

Dave Lee wrote:The approach we took was not to hard code any IDs/values in the application itself.

The identifiers that are used in the CSH calls are automatically generated by the app, based on the internal form name (in the C# app), using the full namespace of the form so that they're unique.
For example, if the full form name was app.module.name, then the app would make a CSH call to Default.htm#cshid=app_module_name (substituting '.' with '_' to make it a valid identifier name).

The big advantage of this is that because you don't include any identifiers in the application code, you never need to change the code - everything can be managed from the alias file.

Is there any way you could provide more details about this method? My company wants to move toward the process of using CSH calls automatically generated by the app. Thanks for anymore detail you can provide.

Donna

dmarino55 wrote:Is there any way you could provide more details about this method? My company wants to move toward the process of using CSH calls automatically generated by the app. Thanks for anymore detail you can provide.

There's not really much more I can add.

When you click help in the form, the code will make a CSH call to the help; e.g. <your site>/Default.htm#cshid=<identifier>

The code calculates the <identifier> using the form's internal name and namespace - which you can think of as the form's internal address/location in the code.
This will also mean that each identifier will be unique.

Because the namespace and form name will be in a format like app.module.form, and Flare identifiers can't include a '.', the code also replaces '.' with '_'.

Dave, does that approach mean that you can't modify the filenames of topic files?

ChoccieMuffin wrote:Dave, does that approach mean that you can't modify the filenames of topic files?

No, the app makes a CSH call using an identifier - nothing to do with filenames.

The identifiers are generated within the app (as described above), so you just need to add these identifiers to your alias file, and set up the topic mappings there.

The main point is that because there are no hard-coded identifiers in the app itself, you don't need to make any code changes in the app to either change or add new CSH links.
All the CSH mappings are managed from your Flare project alias file, so you can control it all there without requiring a code change in the app.

Silly me! Of course, you're right again, as usual.

(Just wish I could persuade our devs to work like that - in a lot of our projects they've hard-coded the html filenames, which is a big PITA.)