Articles in this section

See more

Context-Sensitive Help

Avatar
Anders
  • Updated
Follow

With Context-Sensitive Help (CSH), your users can select a part of your product interface to display the relevant help page. For example, with a software product, you could have an "Info" icon next to a "Balance" option. When the user selects the "info" icon, the help page about the "Balance" feature is opened automatically, so they are taken directly to the relevant information.

Traditionally, context-sensitive help is made by creating a mapping file. The mapping file, sometimes known as a header file, is used to match an id in your product to the id of a page in your documentation. Paligo uses this type of approach for HTML5 outputs and creates the mapping file automatically, as long as you have certain attributes in place.

To set up context-sensitive help, we recommend that you first Create a Mapping File for CSH and then Create a Fallback Page for CSH.

Note

If you need to publish any other type of context-sensitive help, please contact support for assistance.

Create a Mapping File for CSH

To get Paligo to automatically create the mapping file for context-sensitive help:

  1. Get the ids for the application components in your product.

  2. Select the topic or component in the Content Manager to open it in the Editor.

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    Alternatively, you can Create a Topic and edit that.

  3. Select the section element in the Element Structure Menu.

    Close up of Element Structure Menu. It shows the section element is selected and the Go to element option is selected.

  4. Select Go to element.

  5. Add xinfo:appid attribute in Element Attributes Panel and enter the id of the relevant application component in your product.

    If there are multiple components calling the same topic, separate them with semicolons. For example: imagedialog_123;imagebrowser_234

    Element attributes panel shows a section element has been given the xinfo:appid attribute. The value of the attribute is set to imagedialog_123.

    Tip

    Adding the xinfo:appid attribute to the top section element is the typical use case. It is also possible to put xinfo:appid on a sub section inside a topic. The only requirement is that the sub section also has an xml:id, which it would normally have by default.

    If you mark up a sub section, the context sensitive help will open the topic at that location on the page, rather than at the top.

  6. Select Save. Save icon.

  7. Publish your publication. This creates a JSON file that automatically maps any url requests to the relevant topic.

  8. In your product, your developers can call the context-sensitive help using the internal application id's as a string parameter. For example:

    www.youronlinehelp.com/en/index-en.html?contextId=imagedialog_123

    where:

    • www.youronlinehelp.com is the domain where you host your published documentation. In reality, you will have something different, such as your organization's website URL.

    • en/index-en.html is the folder and index file for an English version of your documentation.

    • ?contextId=imagedialog_123 is the context-sensitive help reference.

    The call needs to specify the language folder and the help's index file before the context-sensitive help reference.

Note

To test the context-sensitive help, either:

  • Publish it to your server or a test server (local or web server). This is because the function of fetching data from JSON requires the content to be on a server for browser security requirements.

  • Select to enable local context-sensitive help in the Layout Editor (under General). You can enable this temporarily while testing, and then disable it again when you are ready to publish to your server.

Create a Fallback Page for CSH

We recommend that you create a fallback page, in case there is a problem with one of your context-sensitive help links or pages. The fallback page will be shown if the target page of the context-sensitive link cannot be found.

To create a fallback page for context-sensitive help:

  1. Select the topic or component in the Content Manager to open it in the Editor.

    Content Manager in Paligo. It shows the Documents section contains an Acme 100 Topics folder. Inside the folder there is a publication and many topics, including "Connect to Network (100).

    Alternatively, you can Create a Topic and edit that.

  2. Select the section element in the Element Structure Menu.

    Close up of Element Structure Menu. It shows the section element is selected and the Go to element option is selected.

  3. Select Go to element.

  4. Add the attribute xinfo:appid in the Element Attributes Panel and set the value to not_found.

    Element attributes panel showing that the section element has the xinfo:appid attribute. The value of the attribute set to not_found.

  5. Add the attribute role in the Element Attributes Panel and set the value to notintoc.

    This role will prevent the fallback page from appearing in the table of contents.

    Note

    This is an optional, but recommended step.

  6. Select Save. Save icon.

  7. Publish your publication.

    When you publish your publication, the topic will be used as the fallback page. If the browser cannot find the topic for a context-sensitive help link, it will display the fallback page instead.

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk