I wrote this blog post for MadCap Software back in early January. I have removed most of the numbering WordPress doesn’t seem to handle complex lists well (but Flare does!) but have left the remainder of the text unedited. For the MadCap version of this post, go here.

Flare is great for general Help and for context-sensitive Help. But you may not know that you can build general Help, page-level CSH, AND field-level CSH.

Field level help

There are a few steps (some optional) that are involved with creating field-level Help. Once completed, your developers can easily connect the forms to the Help system.

You can create an entire Help system just for form-based Help or you can have topics in your existing Help system that are defined for just the Help calls from your form. This example will assume that the field-level topics are going to live in an existing Help system.

For the Existing Site

Log on screen

You’ll need to identify the fields that you will be tagging with Help. A good rule would be to only add tags to fields that are not self-explanatory.

Once you’ve identified the fields, you’ll need to define a way to suggest to the users that there is Help for the field. Usually an image will do.

Tip: It may be good to have a few different sized images to match with different sized elements.

For the Flare Project

Content Explorer FolderCreate topics to be used for the field-level Help. It may be useful to keep these separate from existing topics or other field-level topics by storing them in a separate folder. You can style them differently than the rest of your content, exclude them from the search database so they do not appear in search results, etc.

If you are using master pages, you may not want the field-level topics to have breadcrumbs, headers, footers, topics toolbars, etc. It is a good idea to create a new master page and apply it to just these topics.

  • Create a new master page and name it something meaningful: Project > Add Master Page > Choose ‘MasterPage.flmsp’. In this sample it was named FieldLevelTopics.
  • In the master page editor, remove every proxy except the “topic body proxy”. Save.

  • Open the stylesheet from the Content Explorer and find the HTML style, select it. Right-click it and create a class called FieldLevelTopics. In the Unclassified section, find mc-master-page and select then new master page (FieldLevelTopics) from the drop-down. Save.

Now you can apply the FieldLevelTopicsclass to field-level topics. At this point you can also remove them from the search database too.

  1. Open the File List: View > File List
  2. Select all of the topics that are in the Field-Level Topics folder, right-click and select Properties.
  3. In the Properties dialog set the Topic Style Class to the html style that you created FieldLevelTopic. You can also remove the topics from the search database. Press OK once you set the desired options.

Now you will want to change how these topics are displayed. You will do this by creating a skin for these specific CSH calls.

Create a skin for the the field-level Help calls: Project > Add Skin… Name it “FieldLevelTopics“.

Set the following settings in the new skin. Note: some of these are optional and may or may not work for you, depending on how your developers define the popup. These are the settings that I used for a simple JavaScript popup.

  • General tab: Only check the “TOC” option in the Features section. All of the other settings in this dialgo should be un-checked.
  • Size tab: Set the Width to be 300 px and the Height to be 200 px. Everything else should be “0″ or un-checked.
  • About tab: Un-check this option.
  • WebHelp Setup tab: Check the options “Hide Navigation Pane on Startup” and “Exclude Accordion Title”. Un-check any of the browser settings that you don not want, most likely all of them.
  • WebHelp Toolbar tab: Make sure that there are no items listed in the “Selected” column. This shouldn’t affect the project, but it is good to be sure.
  • Topic toolbar tab: Again, make sure that there is nothing in the “Selected” column
  • Styles tab:If you want to remove or change the header with the company logo, you would do it here. Under the “Frame” style select the “Toolbar” class. You will see options under a “General” node to the right. If you want to remove the pane, set the Height to “0 px”. In this example, we will leave it as is “28px”.

Click Save All.

Now set up the Alias file so the developer can link the fields to topics in the Help system. This is done by opening your alias file, adding your field-level topics to it and assigning unique Identifiers. Make sure that you apply the FieldLevelTopicsskin to the Identifiers.

Now just build and test the output with a WebHelp Target: Build > Test CSH API CallsIf prompted to build the target, click OK. If you have to build, when it’s done, go back to Build > Test CSH API Calls and click. This window will open:

Find one of your field-level CSH calls and click Test.

My new field-level CSH call looks like this:

For the Developers:

  1. You will need to provide them with a list of the identifiers so they know which ones to use and for which fields. This is done by suppying them with the header file: Build > Export Header Files…
  2. They will need to write a link to call the popup code and the CSH Identifier. This sample is a JavaScript popup:

<a href=”#” onclick=”return pop(‘MyWebHelp/Default_CSH.htm#TL_Name’)”> <img src=”Help.jpg” border=”0″></a>

When you click on the “?” image, a popup with the field-level Help topic will appear.

Developers can change the look and feel of the popup framework depending on their code and development language used for the application. The above image just uses simple JavaScript to open a new browser window (a little more code is needed but not shown).

Thanks to Laura Johnson for assistance with this blog post.

The following link is a sample project that contains the files and settings outlined in this blog post: FieldLevelHelp

2 Responses to “Using Flare to Build Field-Level Context-Sensitive Help”

  1. Paul Pehrson March 2, 2012

    Hey Laura, great example here with good step-by-step instructions for those less familiar with Flare’s features. Keep up the good work.

  2. Laura March 6, 2012

    Paul, thanks for the compliment! I appreciate it!

Leave a Reply?

Recent Posts

%d bloggers like this: