Field-Level Help using Flare

[jencasty9]

Does anyone know if I can do field-level csh with Flare? If so, what are the steps to implement this? Thanks!

[Nita Beck]

I've created field-level CSH help out of Flare almost exactly as I do for screen-level CSH help.

For each field, I have a standalone topic, and I assign a CSH identifier to it via the Alias Editor, just as I would for screens. Then I give the devs the header file and they hook up the topics to the application.

The only things I did differently was that I turned off all navigational elements in the skin (so now Contents, Index, Search) and set the size of the window, and then in the master page I did not include breadcrumb. The field-level help would just open up a browser window with no other controls than scroll bars (if the topic were long) and the X (close) button.

It's really not all that different from setting up screen-level CSH, and that's fairly well documented in the Flare help system.

[jencasty9]

Thanks, Nita. Do I have to include my field-level topic to my main TOC? I just tried testing my CSH and the topic won't show unless it's in the main TOC.

[Nita Beck]

Thanks, Nita. Do I have to include my field-level topic to my main TOC? I just tried testing my CSH and the topic won't show unless it's in the main TOC.

That will depend on whether you've selected that option (in the target, I'm pretty sure; sorry, I'm going on memory at the moment) to "Exclude files not linked directly or indirectly to the target" (or is it "to a TOC"?).

If you do not have that option selected, then everything in your project, unless otherwise excluded via conditioning, will be included.

If you do have that option selected, then you do need to include those topics on the TOC associated with the target.

[ChoccieMuffin]

I do similar (though not using tripane) and I find it is helpful to include that kind of topic in a logical place in the TOC. I also KEEP the breadcrumbs in so that if the user has clicked Help on a field when they actually wanted the help on the dialog box, they can navigate to it easily. But that's just personal preference.

[RamonS]

I implemented field level help using bookmarks within topics. Rather than one topic for each field I chose one topic for a set of fields within a dialog or page. You can assign map IDs and aliases to bookmarks the same way as you can with topic files. I liked the benefit for the user to be able to scroll through the topic and look at other field descriptions without having to call help for those fields explicitly. One topic per field will make it easier to style it and call it using a different window. The choice is yours. Establish a good naming convention for aliases and a numbering scheme for map IDs if you haven't already.

[Nita Beck]

I implemented field level help using bookmarks within topics. Rather than one topic for each field I chose one topic for a set of fields within a dialog or page. You can assign map IDs and aliases to bookmarks the same way as you can with topic files. I liked the benefit for the user to be able to scroll through the topic and look at other field descriptions without having to call help for those fields explicitly...

We need a Like button on the forums! Love this idea; might even get a chance to implement it for a client for whom we're currently doing window-level help. We might be challenged though in that many field descriptions are stored in snippets that are then used in multiple topics. I'm sure we could figure it out. Again, thanks for the idea!

[jencasty9]

That will depend on whether you've selected that option (in the target, I'm pretty sure; sorry, I'm going on memory at the moment) to "Exclude files not linked directly or indirectly to the target" (or is it "to a TOC"?).

This solved my problem. Thanks again, Nita Sorry, one more question. I removed all toolbar from the skin, but the company logo and search bar is still showing up on the CSH window. I'm not sure if this is a bug or I'm just not doing it right.

[jencasty9]

I implemented field level help using bookmarks within topics. Rather than one topic for each field I chose one topic for a set of fields within a dialog or page. You can assign map IDs and aliases to bookmarks the same way as you can with topic files. I liked the benefit for the user to be able to scroll through the topic and look at other field descriptions without having to call help for those fields explicitly. One topic per field will make it easier to style it and call it using a different window. The choice is yours. Establish a good naming convention for aliases and a numbering scheme for map IDs if you haven't already.

Thanks, RamonS for your suggestion. We're launching a new web application and it's my first time implementing CSH (both page and field level) for our help file, so I'm still learning. What are your tips for naming aliases and numbering them?

[Nita Beck]

...one more question. I removed all toolbar from the skin, but the company logo and search bar is still showing up on the CSH window. I'm not sure if this is a bug or I'm just not doing it right.

Are you creating HTML5 output and, if yes, tripane or top nav? At least for tripane, I know you can edit Header > Layout > Display and change "Display" to "none". That'll hide the header. You might also have to make its Height something like 0px. This is all in theory; I've not tried this before for HTML5 output.

[jencasty9]

I set the Height to 0 px, but it's still showing. Oh wells... I'll leave it be for now. Thanks for all your help

[RamonS]

As far as naming convention for files goes, see my post here: viewtopic.php?f=4&t=21556&p=109785#p109785
You could follow the same approach for aliases plus a descriptor added such as "_FLH" when the alias is to be used for field level help rather than for an entire topic. Map IDs may not be necessary when you can use aliases, but you can translate the file/alias naming convention to a numbering scheme.

[rhetoric101]

As far as shutting off the header in HTML5, I ran into a bug in Flare (#55794) where you can't have multiple skins for HTML5. Our main project is in HTML5, so I thought I could keep the field-level context sensitive help in HTML5, too, but Flare won't apply my field-level skin that dumps the header. The only way I've been able to get around that is to take Dave Lee's suggestion and make two targets (see "Field-Level Help Inserting Logo From Target Skin"), although I'm not sure if I could use the cool trick mentioned above about keeping breadcrumbs.

If you have two targets, one for your main Help and one for field-level Help, you can avoid duplicating all your main Help topics over in the field-level structure by using Nita Beck's trick of inserting all your field-level topics in a field-level TOC and then selecting "Exclude content not linked directly or indirectly from the target" in the Advanced tab of the field-level target. This gives you a build of field-level Help without the extra files from your main Help.

I might add that I like the idea of using a field-level TOC as another way to keep track of where the topics are embedded in the application. Maybe this is going to turn into a challenge to maintain, keeping both the alias file and the TOC in sync, but if I want to keep my main Help files out of the field-level help, I think I need to use the TOC. I suppose I could create an entirely separate project for my field-level Help that does not have a TOC, and it would not get polluted by my main Help topics.

[SusanL]

As far as shutting off the header in HTML5, I ran into a bug in Flare (#55794) where you can't have multiple skins for HTML5.

Have you heard anything back from Madcap on this HTML5 issue? I don't think there is a way I can check on the status of a bug submitted by somebody else. I just discovered that our UX team wants our page-level CSH help to be stripped of header and TOC. I could create a separate help target, skin, and TOC as suggested previously, but the development team is already complaining about how many files there are in the help, so I doubt two help systems will go down well.

[NorthEast]

As far as shutting off the header in HTML5, I ran into a bug in Flare (#55794) where you can't have multiple skins for HTML5.

Have you heard anything back from Madcap on this HTML5 issue? I don't think there is a way I can check on the status of a bug submitted by somebody else. I just discovered that our UX team wants our page-level CSH help to be stripped of header and TOC. I could create a separate help target, skin, and TOC as suggested previously, but the development team is already complaining about how many files there are in the help, so I doubt two help systems will go down well.

I've reported this too, and I'm pretty sure it hasn't been fixed (I wouldn't really bet on it being fixed either, as it's been broken since HTML5 first appeared, and would only be for tripane and not top nav skins).

I would definitely suggest using two separate targets.

For your field-level help, create a HTML5 target, and set the Skin to (none).
Then your output will not include any skin elements, it will only include what you have in your topic or master page.

Why would your developers care how many files are in the help?
For them, it's pretty easy - they just need to link to your main help file and include the cshid.

[jsandora]

Not sure if this is the same thing you're trying to do, but we use Flare to deliver "inline help" (or embedded help), which amounts to pop-up windows within our applications that display topics based on the area of the page from which the help window was opened. These are in conjunction with the full online help system. These pop-up windows are individual topics in the online help, but not linked in the TOC. We figured out how to remove all the top-nav header stuff from the topics so it's a much cleaner presentation.

Here's the thread on how we got there: viewtopic.php?f=9&t=21642

[NorthEast]

We figured out how to remove all the top-nav header stuff from the topics so it's a much cleaner presentation.

If you set the target skin to (none), then the top nav header won't be included in your topics in the first place.

[jsandora]

If you set the target skin to (none), then the top nav header won't be included in your topics in the first place.

Does that work when the topics in question are a part of a "usual" online help system?

[NorthEast]

If you set the target skin to (none), then the top nav header won't be included in your topics in the first place.

Does that work when the topics in question are a part of a "usual" online help system?

Yes, the topics are the same, you'd just have two targets.
You'd have a target for field-level help that doesn't have a skin, and the target for your "usual" help would have a top nav skin.

[SusanL]

Why would your developers care how many files are in the help?
For them, it's pretty easy - they just need to link to your main help file and include the cshid.

Anything that increases the overall size of what we give to the customer gets complained about. Specifically, though, they had been dealing with a .CHM file that was loaded onto individual clients, and now they are doing server-side help that lives on customer servers, so it's a paradigm shift.

[RamonS]

Why would your developers care how many files are in the help?
For them, it's pretty easy - they just need to link to your main help file and include the cshid.

Anything that increases the overall size of what we give to the customer gets complained about. Specifically, though, they had been dealing with a .CHM file that was loaded onto individual clients, and now they are doing server-side help that lives on customer servers, so it's a paradigm shift.

Since when is drive space on a server an issue? Even on a client desktop a few GB drive space should not be a concern. I can see that to be an argument for mobile or embedded devices or if the installer is typically pulled over a dial-up connection, to a lesser extent also for physical media, but there is space for a lot of bits even on a CD.

[GDonn]

Not sure if this is the same thing you're trying to do, but we use Flare to deliver "inline help" (or embedded help), which amounts to pop-up windows within our applications that display topics based on the area of the page from which the help window was opened. These are in conjunction with the full online help system. These pop-up windows are individual topics in the online help, but not linked in the TOC. We figured out how to remove all the top-nav header stuff from the topics so it's a much cleaner presentation.

Here's the thread on how we got there: viewtopic.php?f=9&t=21642

Here's another way to do this: http://www.madcapsoftware.com/blog/2012 ... tive-help/ This way you don't have to have 2 stylesheets.

[TheGreatAndPowerfulOz]

Here's another way to do this: http://www.madcapsoftware.com/blog/2012 ... tive-help/ This way you don't have to have 2 stylesheets.

Thanks for this link, GDonn; just the sort of clear, step-by-step info I was looking for