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:

    1.  Log on screenYou’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.

 

  1. 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:

    1.  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.

 

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

 

      1. 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.
        Styles

 

    1. Now you can apply the FieldLevelTopics class 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.
        Topic Properties

 

    1. Now you will want to change how these topics are displayed.  You will do this by creating a skin for these specific CSH calls.
      1. Create a skin for the the field-level Help calls: Project > Add Skin… Name it “FieldLevelTopics“.
      2. 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.
        1. General tab: Only check the “TOC” option in the Features section.  All of the other settings in this dialgo should be un-checked.
        2. Size tab: Set the Width to be 300 px and the Height to be 200 px.  Everything else should be “0” or un-checked.
        3. About tab: Un-check this option.
        4. 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.
        5. 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.
        6. Topic toolbar tab: Again, make sure that there is nothing in the “Selected” column
        7. 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”.
          Skin Styles
        8. Save All

 

    1. 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 FieldLevelTopics skin to the Identifiers.
      Alias

 

  1. Now just build and test the output with a WebHelp Target: Build > Test CSH API Calls.
  2. Build and Test

    If 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:
    CSH Test
    Find one of your field-level CSH calls and click Test.

    My new field-level CSH call looks like this:
    CSH Test Results

 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.

Field-Level Help

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

About The Author

Jose Sermeno

About Jose Sermeno

With over 10 years of experience in the software industry, Mr. Sermeno brings a wealth of knowledge and expertise to the product evangelist team, helping introduce new users to everything MadCap Software. In his spare time, Jose is the Project Director for San Diego City Robotics, the San Diego community college systems robotics program, and enjoys working in software design and open source hardware development. Prior to joining MadCap in late 2010, Jose ran a Drupal development shop, and was an application manager for Temple University Health System.

Last Modified: October 17, 2014

This entry was posted in MadCap Flare, MadCap Software, Tech Comm, Tips & Tricks. Bookmark the permalink.

Comments

  • Pingback: Using Flare to Build Field-Level Context-Sensitive Help | A Flare for Help

  • Vilma Zamboli May 14, 2012 at 10:26 AM

    with Flare 7.2 inserting a height=0 to the Styles tab of the skin is giving an Internal error. i had to set it to 1px

  • Arnold Burian May 25, 2012 at 10:49 AM

    Is it possible to have the size of the tooltip change relative to the amount of text?

    Thanks!

    • David Ferriot David Ferriot May 31, 2012 at 10:17 AM

      I believe that would be up to your developers to code it. Flare provides the compiled content and the CSH string to it but the popup container is something the web designer would need to code/style.

      • Arnold Burian June 1, 2012 at 1:10 PM

        Thanks, David. Normally, the size of the window is controlled by the skin. Hm.

  • Deborah December 10, 2013 at 10:22 AM

    I’m using Flare8 and cannot find a way to remove the header with company logo from my CSH topics. The instructions for doing this refer to a “Frame” style with a “Toolbar” class but that’s not an option with Flare8. I’ve changed the header height to 0px but that doesn’t work. I’ve also changed the logo selection to None.
    Any suggestions would be greatly appreciated.

    • Jennifer White Jennifer White December 16, 2013 at 10:05 AM

      Hi Deborah, The “Frame : Toolbar” style is located in the Skin in the Styles tab and it is available in Flare V8.
      Let me now if that clarifies things for you!

      Jennifer

  • Martin March 15, 2017 at 12:48 PM

    How can I make this work with a C# based application to HTML5 help system?

  • Laura D. May 25, 2017 at 9:02 AM

    Is this solution Section 508 compliant? I can’t tell from the way it is described if it meets all criteria. Section 508 compliance is a must for my work.

Have Something to Say?

Your email address will not be published. Required fields are marked *