Creating Embedded Help on the Web

Doc-To-Help’s NetHelp 2.0 is architected to make it easy to embed a single topic, or an entire Help system, into a web page. This means you can create embedded help on a website, and at the same time implement a continuous publishing model, since you can now stream updated content to your website without additional web development.

Here’s an example of a single topic embedded on a web page (you can embed your help anywhere on a page, and change the window size, of course.)


You can also embed an entire help system on your webpage.

This isn’t very difficult to do; you just need to do some lightweight front-end configuration to your web site. Your Help system does not even need to be hosted on the same web server as your main site. If that is your situation, you would add an iframe, because an iframe makes it possible to store your web site and the NetHelp 2.0 target on different servers (domains). If both your Help system and your website will be hosted on the same web server, an iframe is not needed.

Embedding a NetHelp 2.0 Target in an iframe

This method allows your web site and NetHelp 2.0 target to be stored on different servers (domains).

  1. Publish your built NetHelp 2.0 target to a server, for example, http://mysite.com/help/mytarget/ (The full Target URL to NetHelp 2.0 is: http://mysite.com/help/mytarget/default.htm)
  2. Add an “iframe” element to your webpage that contains the NetHelp 2.0 target. The iframe tag must have the “src” attribute set to the default NetHelp 2.0 page (“default.htm”) in the target folder.

For example, to embed a full NetHelp 2.0 Target without parameters add:

<iframe src=“http://mysite.com/help/mytarget/default.htm”></iframe>

To embed a single topic on a web page, add:

<iframe src=“http://mysite.com/help/mytarget/default.htm?topiconly=true”></iframe>

The URL in the “src” attribute can be used to set NetHelp 2.0 target parameters if desired. These parameters are explained in NetHelp 2.0: Supported Parameters and How to Use Them.

In case you were wondering, here is the code used for the embedded help above …

<iframe src=“http://helpcentral.componentone.com/nethelp/c1intellispell/default.htm?topiconly=“true” width=“300px” height=“300px”></iframe>

This code could be used to embed that entire Help system on a webpage …

<iframe src=“http://helpcentral.componentone.com/nethelp/c1intellispell/default.htm” width=“1000px” height=“350px”></iframe>

Generic example:

<!DOCTYPE html>

<html>

<head>

<title>IFrame example</title>

<meta http-equiv=“Content-Type” content=“text/html; charset=utf-8” />

<meta http-equiv=“X-UA-Compatible” content=“IE=edge” />

</head>

<body style=“padding: 10px;”>

<p>Some text before help frame.</p>

<!– HELP FRAME –>

<iframe src=“http://mysite.com/help/mytarget/default.htm”></iframe width=“800px” height=“400px” >

<!– END OF HELP FRAME –>

<p>Some text after help frame.</p>

</body>

</html>

Embedding a NetHelp 2.0 Target without an iframe

You can embed a NetHelp 2.0 Target into any HTML element (for example, into a DIV element).

This option is only available if the NetHelp 2.0 target and the container page (into which you embed the NetHelp 2.0 target) are stored in the same domain.

  1. Publish your built NetHelp 2.0 target to a server, for example, http://mysite.com/help/mytarget/ (The full Target URL to NetHelp 2.0 is: http://mysite.com/help/mytarget/default.htm)
  2. Add a container element (any HTML element) to your page, which will contain the NetHelp 2.0 target.
  3. The container must have the CSS property “position” set to either the “relative”, “absolute” or “fixed” value. This is a restriction of the Doc-To-Help standard themes (Tabs and Accordion).

    You must also set the height for the container if you want to display NetHelp 2.0 target in full mode (you do not need to do this for topic only mode).

    For example, <div id=“mytarget” style=“position:relative; height:500px;”></div>If you want to display the NetHelp 2.0 target in topic only mode, the container element may look like this: <div id=“mytarget”></div>

  4. Add the “script” tag to the “head” section of the page. This script tag must have the “src” attribute set to the “js/nethelp.connect.js” file located in the NetHelp 2.0 target folder. You can also set the following optional attributes for this tag to set up the target:
  • “data-placeholder”—specifies the jQuery-selector of the container element created in step 2. If this attribute is missed then the NetHelp 2.0 engine will search for an element with the attribute “data-c1-role” equal to the “nethelp” value, if no such element is found the “body” element will be used as a container for the NetHelp 2.0 target. The NetHelp 2.0 target is placed into a container element and replaces all its content.
  • “data-start”—specifies the URL of the topic that will be shown instead of the default topic when the NetHelp 2.0 target is loaded.
  • “data-topiconly”—if set to “true” the NetHelp 2.0 target will be displayed in topic only mode (without header, toolbars, and Contents, Index and Search tabs).
  • “data-settings”—specifies the URL of the NetHelp 2.0 target settings file (by default it is the “settings.xml” file in the root target folder).

For example: <script type=“text/javascript” src=“/help/mytarget/js/nethelp.connect.js” data-placeholder=“#mytarget”></script>

Note: If you are viewing the web site from the local file system, the NetHelp 2.0 target folder must be located in a subfolder of your site. Otherwise your browser may block the NetHelp 2.0 files.

Generic example:

<!DOCTYPE html>

<html>

<head>

<title>Inline example</title>

<meta http-equiv=“Content-Type” content=“text/html; charset=utf-8” />

<meta http-equiv=“X-UA-Compatible” content=“IE=edge” />

<script type=“text/javascript” src=“/help/mytarget/js/nethelp.connect.js”

data-settings=“/help/mytarget/settings.xml”

data-start=“/help/mytarget/Documents/home_topic.htm”></script>

</head>

<body style=“padding: 10px;”>

<p>Some text before help frame.</p>

<!– HELP FRAME –>

<div data-c1-role=“nethelp” style=“position:relative; width:800px; height:400px;”></div>

<!– END OF HELP FRAME –>

<p>Some text after help frame.</p>

</body>

</html>

Wrapping up …

It is easy to embed Help on a web site, whether you want to serve up individual topics, or entire systems.

If you are interested in embedding help within a desktop application, you may want to consider the ComponentOne Dynamic Help control. See Dynamic Help for Winforms. This control was used to create the Dynamic Help pane in Doc-To-Help.

Note: This functionality is available in Doc-To-Help 2012 V2, which you can download here.

This entry was posted in Doc-To-Help and tagged , on by .

About Nicky Bleiel

I am the Lead Information Developer for Doc-To-Help and a Doc-To-Help trainer. I have 19 years of experience in technical communication; writing and designing information for software products in the documentation, media, industrial automation, simulation, and pharmaceutical industries. I am the President of the Society for Technical Communication and have presented talks at the STC Summit, WritersUA, tcworld, CIDM (Content Management Strategies/DITA North America), and LavaCon on many topics, including embedded help, tools and technologies, user assistance design, single sourcing, wikis, social media, agile, and convergence technical communication. I have been published in STC's Intercom, Tieline, STC conference proceedings, tcworld magazine, TechCom Manager Newsletter, and the WritersUA and the Content Wrangler websites. Additionally, I teach Technical Writing at the Community College of Allegheny County.

4 thoughts on “Creating Embedded Help on the Web

  1. Theis Dræberg

    Hi, first off, great software and great help on this site. The iframe thing works for me.

    However, when looking up the jQuery parameters in your documentation. I cannot get this to work:
    Open topic with hidden NetHelp elements (no tabs, header, toolbars):
    http://mysite.com/target/default.html?topiconly=true#!documents/topic.html
    ____________
    Which would translate to (using my site):

    http://xemrav.dk/vaerneguiden/index.html?topiconly=true#!documents/absorbenter.htm

    I know it exists, and you can find the page by going through the menues.

    Any help much appreciated!

    Thanks!

    - Theis D.

    1. Theis Dræberg

      Seems that I was the problem. My undoing is I created a new folder wherein I located the files, thus “renaming” the folder name set in D2H from NetHelp to vaerneguide.

      Now the target has the same name as the folder and it works perfectly.

  2. David Watson

    I want to put context-sensitive help (or at least page sensitive help) on a non-public web application that we have (written in C# ASP.NET .Net Framework 3.5) that has hundreds of pages, but from your description it seems we would have to edit the HTML of every page and we cannot do that. Could you please explain how we could have everything database driven (SQL Server), and each page is an ASPX file, so the [Help] icon on the page could look up the Help table to get the parameter and pass it to Doc-to-Help and display the relevant help information?

    1. Nicky Bleiel Post author

      If your website has a template (master page), then you could modify it to include a container for a NetHelp topic and the change will be reflected in all derived pages. Regarding your other questions, I would need specific information about your project to answer. Could you please email me at nickyb *at* doctohelp.com? Thanks!

Leave a Reply