Partager via

Displaying Contextual Help in a Custom Task Pane

  • Article

With all the wonderful features in the new Office apps, it's easy to get lost!  InfoPath is no exception, and when you make clever use of the new features, you'll want to make sure that users understand how your form is supposed to work.  Wouldn't it be great if you could display contextual help information as the user navigates to fields in your form.  With the "Context Changed" event, you can execute custom code when the user filling the form causes the context node to change.  This will fire when the user focuses a control bound to a different DOM node than the current context node.

 

Files you'll need

The solution we provide here uses some resource files.  Download the attached files to accomplish the scenario.

1. "CustomTaskPaneHelp.htm" - The HTML file that will be displayed in the custom task pane.  We will manipulate this document at runtime from custom form code to display the contextually appropriate help information.  Just update the styles in this file to change the appearance of the contextual help in the custom taskpane.

2. "Help Strings.xml" - This file is a basic xml file that contains mappings from local node names to the title and help contents for the node.  This file will be consulted to retrieve the help information to be displayed in the custom task pane.

3. "CustomTaskPane.cs" - This helper class wraps the HtmlTaskPane object to access elements in the custom task pane.  This will be added to your VSTA project.

4. "FormCode.cs" - This contains the code to integrate the custom taskpane into the form template.

Note that this method works in InfoPath 2003 and 2007, but this tutorial will walk you through the steps in for InfoPath 2007 - the UI is slightly different in 2003, but you can still make it work. Since task panes are a rich-client only feature, this method is not supported in browser-enabled form templates.

 

Construct your help resource file

Assuming you've designed your form template already, you'll have a nicely populated data source, replete with variously named nodes.  Now add contextual help data for nodes in the main and secondary data sources:

1. Open the "Help Strings.xml" file in notepad (or another text editor.)

2. Add a "Help" element for the data source node:

  • Set the "nodeName" attribute's value to "<node prefix>:<Name in Data Source Pane>"
  • Set the "Title" element's value to the heading that you want to display for this node's contextual help.
  • Set the "Contents" element's value to the body of this node's contextual help.

3. Repeat step 2 for all nodes for which you want to display contextual help so that you have something like this:

<?xml version="1.0" encoding="utf-8" ?>
<HelpStrings>
   <HelpString>
      <Help nodeName="my:TextField">
         <Title>Text Field</Title>
         <Contents>Help for my text field.</Contents>
      </Help>
      <Help nodeName="my:RichTextField">
         <Title>Rich Text Field</Title>
         <Contents>Help for my rich text field.</Contents>
      </Help>
   </HelpString>
</HelpStrings>

 

4. Save the file to a shared location

NOTE:  If you want to be able to update this help data without having to re-deploy the form template, the shared location should be accessible to all users that will fill out the form.  If, on the other hand, you do not care about that, then you can just save the file locally and add it as a resource file to the form template.  See below…

 

Add the data source that will provide your contextual help data

Now that you're help strings are all set, we need to add a reference to the help strings so that the form template can access them.  We'll do this by adding a data connection to query the xml file from a shared location or resource file.

1. Tools >> Data Connections >> Add

2. Select Receive Data, then XML Document

3. Specify the location of the help strings document (Help Strings.xml)

  • If, as noted above, you want to include the help strings as a resource file in the form template, just click "Next >". Including the file as a resource file guarantees that it will always be accessible to the form template, but the form template will have to be updated if you need to change the help strings.
  • If, on the other hand, you would like to access the help strings file from a shared network location or web server, then select "Access the data from the specified location" and then click "Next >". Accessing the file from a shared location may fail if the shared location is unavailable, and there may be some delay due to network traffic.

4. Check the "Automatically retrieve data when form is opened" check box and click "Finish" / "Close".

 

Enable the custom task pane in your form template

Custom task panes are not enabled by default.  We'll specify that the custom task pane should be displayed, and its content should be rendered from the "CustomTaskPaneHelp.htm" file.

1. Tools >> Form Options >> Programming

2. Check the "Enable custom task pane" check box. Type a name for the custom task pane in the "Task pane name" field.

3. Add the "CustomTaskPaneHelp.htm" file as a resource file.

  • Click Resource Files >> Add…
  • Browse to the "CustomTaskPaneHelp.htm" file and click Open / OK.

4. Select "CustomTaskPaneHelp.htm" from the "Task pane location" drop-down list.

 

Add the code to manage the context change and display the contextual help information

1. Tools >> Programming >> Context Changed Event; this will create the VSTA project and insert the "Context Changed" event handler.

2. Add the "CustomTaskPane.cs" file to your project

  • Right-click the top-level project node.
  • Click "Add" >> "Existing Item…"
  • Browse to the "CustomTaskPane.cs" file and click "Add".
  • IMPORTANT: Edit the Namespace of the "CustomTaskPane.cs" file to be the same as that of your form code file.

3. Integrate the code in the attached "FormCode.cs" file into your VSTA project.  Make sure you copy the contents of the "FormEvents_ContextChanged" method, as well as the private properties and variables.

4. Build and save your form template.

 

 

Make the form template full trust

  1. Tools >> Form Options >> Security and Trust
  2. Uncheck the "Automatically determine security level" checkbox. Select the "Full Trust" radio button.
  3. Click "OK"
  4. Save and publish the form template. You will need to publish the form template as an installable form template (.msi) or digitally sign the template; detailed instructions are here.

Now, when users fill out your form, contextual help will be displayed for each node as the user clicks on a control bound to it.  As long as you've included help information in the help strings file, you'll see the help information in your custom task pane!

Forrest Dillaway
Software Design Engineer in Test

ContextualHelp.zip

Comments

  • Anonymous
    April 02, 2007
    In sommige situaties kan het handig zijn om gebruikers extra hulp te bieden bij het invullen van een...

  • Anonymous
    August 28, 2007
    If you're seeing the HTML source in the TaskPane, instead of the rendered help, see the following note: In IE7, security zones have changed. The local machine is no longer running in intranet but in a separate zone tied to the internet zone. In the IE security settings for the Internet zone, check the following option under Miscellaneous category: “Open files based on content, not file extension”. This needs to be set as Enabled (which is the default setting). Depending on your security domain of the xsn, you might need to check the same settings for the other zones (local intranet, trusted, etc).

  • Anonymous
    August 17, 2008
    The comment has been removed

  • Anonymous
    August 07, 2009
    This is so much help .. thank you so much. I hope to see more in this topic soon.

  • Anonymous
    September 17, 2010
    How do I do this with InfoPath 2010!?

  • Anonymous
    September 17, 2010
    The custom taskpane is still supported in IP2010. You need to make sure you're designing a Filler form for the option to show up in Form Options. To access the Form Options dialog, click File, Info, Form Options.

  • Anonymous
    September 17, 2010
    Thanks! I have the custom help pane displaying when the form is run now, but the context change is not working. I get the following error when I try to build the form: 'CustomTaskPane' is a 'namespace' but is used like a 'type'. Any ideas? I'm almost there I think, but not quite!

  • Anonymous
    September 27, 2012
    I can not get this to work, can you put a working form on this site?