March 2015
By Marc Achtelig

Image: @ Mt Kang/ 123rf.com

Marc Achtelig is an engineer who has been documenting German and English language software for over 20 years. He operates an engineering firm for technical communication with a focus on software documentation and documentation of software driven products in the Nurnberg region in Germany. He has also authored some  technical books on planning, designing and editing technical documentation.


marc.achtelig[at]indoition.de
www.indoition.de


 


 

Help with additional functions

Many online help systems can do much more than what they offer today. As modern websites already show, many practical things can be set up with some ready-to-use Open-Source-JavaScript-libraries or jQuery-Plug-ins. This does not even require in-depth programming knowledge.

Most online help is clearly limping behind state of the art technology in web design. To some extent, this is due to the help authoring tools that traditionally support only specific functions. However, it is also due to technical writers, many of whom believing that they lack the technical proficiency to make enhancements. Thanks to ready to use open source JavaScript libraries, much can be done without any programming knowledge. Some basic knowledge of HTML is sufficient.

Through this article, we would like to show you how to incorporate new functions in online help. We use specific examples, but the general procedure also applies for enhancing any other functions. We will be looking at solutions for the following in detail:

  • Sortable tables
  • Automatically appearing buttons for scrolling back to the start of the page
  • Tabs within a topic
  • Elements that do not scroll up from the screen
  • Images with zoom function

We have also prepared a demo help online for the examples, where you can try out the respective functions [1].

Three basic steps

We use the help authoring tool Mad-Cap Flare to implement our examples. The implementation works almost the same with other help authoring tools; in fact, it might be even simpler. The basic procedure is always the same:

  1. You download the script to be used. Most of the scripts are subject to an Open-Source-licence and can be used for free in commercial projects.
  2. You copy the script in your project directory. The most appropriate location depends on the authoring system that you use. In each case, it is important that the system takes over the script in the directory of the help later when the help is generated. Otherwise, the script has to be manually copied in the target directory of your help each time the help is generated or the script saved on a web server under a fixed URL.
  3. If you want to use the script in several of your topics, incorporate it on a master page or in a topic template, depending on the help authoring tool used. If you want to use the script in just individual topics, incorporate it only in this topic. The documentation for the respective script will tell you how a script can be incorporated exactly.

Simple matter

Most scripts are delivered along with at least one example, based on which you can test the function. However, some developers pack in a lot in their demos. In such cases, it makes sense to create a copy of the demonstration and to reduce it once systematically to the contents and functions that you actually require. Then you will have the ideal working template.

You can almost always manage without in-depth programming knowledge. If a solution turns out to be too complicated or does not function partly, simply move to a comparable script. Considering the huge selection available, there is almost always a suitable alternative.

Majority of jQuery-Plug-ins

Most of the ready to use scripts today are so-called jQuery-Plug-ins. The Open-Source-library jQuery simplifies basic things like document manipulation, event handling and animation [2]. Such scripts are used a million-fold today.

If you use a jQuery-Plug-in, then you need not deal in more depth with jQuery itself at all. You only need to ensure that jQuery is also integrated in your help pages in addition to the respective script. Most of the help authoring tools already do this automatically today, because even help authoring tools fall back on jQuery-routines.

You will keep seeing the so-called jQuery function in jQuery-Plug-ins, which is abbreviated with a $-symbol, e.g.:

$('#demoTab').easyResponsiveTabs();

This means the same as:

jQuery('#demoTab').easyResponsiveTabs();

For the implemented JavaScript-functions to work, Java­Script must be enabled in the browser of the user. However, since online help generated by most help authoring tools innately runs only with active JavaScript, we can consider this prerequisite as a given for our extensions.

Example 1: Sortable table

Let us first look at an example of how we can make a table sortable for the user with a table included in a topic. A script automatically sorts the rows in the table according to the values in the column when a user clicks on the column heading in such a table. The sorting sequence is reversed on clicking again on the column heading. Such a function is highly suitable for value tables and offers true benefit vis a vis documentation printed on paper.

In the first step, we download the script and copy it in our Flare- project directory [7]. In this case, we really require only this single script since it is not based on jQuery.


Figure 1: Copy file with the JavaScript in the project directory.
Screen: Marc Achtelig

 

Now we integrate the script in the topic, in which we want to use it. In Flare, we use the view “Text Editor” for this.


Figure 2: Integrate script in topic.
Screen: Marc Achtelig



According to the documentation provided with the script, we now have to assign the class “sortable” to each table, if it is supposed to be sortable. Here too we use the “Text Editor” again, refer to figure 2.

That would be all. The table is sortable when the help is generated.


Figure 3: Table before and after sorting.
Screen: Marc Achtelig

 

It needs to be mentioned that the table in figure 3 is not specially formatted. If you design your table to be more challenging, the script functions similarly.

Example 2: Scroll-function at the beginning

Our second example concerns a jQuery plug-in [4]. Along with the script, the jQuery library also must be referenced in the topic.

It can be tricky to set up the reference. Generally, jQuery must be integrated before the plug-in. Help authoring tools such as Flare integrate jQuery and their own scripts but often only when generating the help and then always at the very end of the <head>-section of a topic.

Therefore, often the only solution is not to integrate the script in the <head>-section of our topic as stated in its documentation, but at the beginning of the <body>-section. This works the same way, but then our script is placed after the scripts of the help authoring tools as required.

In case of our script for the scroll function, it appears in Flare, as can be seen in Figure 4.


Figure 4: Script in body section of the topic.
Screen: Marc Achtelig

 

Again, that was it. After generating the help, a button automatically appears when required to go back to the start of the page.


Figure 5: Button to go back to the start of the page.
Screen: Marc Achtelig

Note: In practice, a script should appear in every topic in most cases like in our second example and not just in a single topic. You can then integrate the script in Flare in a master page as well and thus need not repeat the integration. Other authoring systems offer similar functions to edit master pages or topic templates.

 

Example 3: integrated tabs

In the third example, we look at some special features that can generally be important. Some scripts require us to add additional things in the HTML code of a topic. In our script for the tabs these are additional tags for instance, which mark the boundaries for what content should appear on which tabs [3].

In most help authoring tools, such HTML-snippets can be inserted at any position in a topic. In Flare, however, this works only in the Code view “Text Editor”. If you prefer to work with the “XML-Editor” of Flare, then you can only insert a JavaScript there and not HTML. However, this stills works with a trick: Instead of HTML, simply insert a JavaScript, which in turn writes the HTML with the help of the JavaScript command “document.write()”. E.g.: Instead of the HTML-Code “< d i v >“ insert a JavaScript with the content “document.write('< d i v >')”.

 

In addition, there is one more solution especially for Flare: If you reference additional CSS in the application, e.g. as our script for the tabs requires, then Flare deletes this reference completely while generating the help. Here too it helps to pack the concerned statement in a document.write()-command.


Figure 6: CSS-Reference in Flare hidden in a Java-script.
Screen: Marc Achtelig

 

How the tabs will appear for the user is shown in figure 7.


Figure 7: Tabs in a topic generated with Flare.
Screen: Marc Achtelig

 

Fixed elements and zoom effects

Two more interesting examples for use in online help are also found in the demonstration.


Figure 8: Element that does not scroll upwards from the image.
Screen: Marc Achtelig


Figure 9: Image with zoom effect.
Screen: Marc Achtelig

 

A use case for a “sticky item” that does not scroll upwards from the image could be the figure of operating elements of a technical device [5].

A use case for a figure with zoom effect could be a figure of a larger system for which a user can zoom for details, for example [5].

The integration of these functions in the help runs as it does in the cases that have already been described. Take a look at the source code of the corresponding HTML pages if you are interested.

Possible conflicts

When you integrate a ready JavaScript in a help generated with a help authoring tool, you must always be aware this can also lead to conflicts with existing functions. Therefore, completely test the function of your help after the integration of the script. If there are problems, you will either need to customise the script or change to a comparable script.

If a CSS file also belongs to a script, then the information existing there can conflict with the information in the CSS file generated by your help authoring tool. You might have to consolidate the information here. An example: A CSS file is part of the solution implemented for the tabs, in which formats are defined for the <body>-tag. If you have different settings defined in the CSS-file of your help, your must consolidate these with those of the script. If necessary, you need to experiment a bit here to fine-tune your solution.

Solutions for errors

Just as a reminder, let me state once again that we are discussing uncompiled help systems (WebHelp) here. In Microsoft HTML-help (CHM-files) many things do not function, but there are exceptions. One example for this is the script shown for sorting tables, which works without issues even in a CHM file.

If a script does not run as desired, it can often be traced back to one of the following reasons:

  • Wrong jQuery-Version – many help authoring tools already internally integrate jQuery in the generated HTML pages, to enable using it in scripts created by the tools. However, the jQuery version used here may not be the most current and may not be compatible with the version of a specific plug-in. If one of the plug-ins you have integrated does not function as expected, always integrate the most recent version of jQuery as well, specifically in the source code of a topic after the jQuery version integrated by the help authoring tool (see remarks in example 2).
  • The help authoring tool has again overwritten your code customization – depending on the help authoring tool you must note that your tool doesn’t again reverse your changes to the source code unnoticed, when you process a topic or object with the functions of the help authoring tool.
  • Relative addresses in the script call do not match – in some help authoring tools you can define that all generated topics should not lie in the same directory. In such a case, you must ensure that valid path details for the scripts and CSS files are present in each topic in spite of this arrangement. In such a case, it is simplest either to work with the full path details or to copy a script into each directory in which the topics lie.

Systematic error search

If a script does not do what it is supposed to, then you can usually solve the problem as follows:

  1. Generate the help in which the script is already integrated, but in which it does not function.
  2. Open a topic of the help in a browser in which the script should actually function.
  3. Open the HTML file of the same topic in an HTML editor or in a text editor in parallel.
  4. Identify the cause of the error. You can save the HTML file and reload it in the browser at any time for testing. You then immediately see the impact of the change.
  5. Go back to your authoring system only once the changed HTML file functions as expected and then make the corresponding changes there so that the HTML page is generated in the desired form in future.
  6. Now generate the help again and test the result. If required, repeat the process from step 2.

Better and without efforts

The integration of a ready to use JavaScript in an online help can usually be implemented without great programming knowledge and can equip a help with completely new functions. However, everything that is technically feasible is not meaningful. The additional functions that are actually a true win for you and not just a game for your own help systems depends on the content and target group of the help. Take a moment to search the net for scripts that are available for free. You will be astonished to see what can be found there. Just try out some scripts yourself. The effort is low, but the effect is often great.

 

Links to sources and plug-ins

[1]    Sample help: www.indoition.com/demos/scripts-flare
[2]    Prerequisites for most of the JavaScript-libraries is jQuery
[3]    JavaScript for responsive tabs
[4]    JavaScript for  Scroll-Back-To-Top-Function
[5]    JavaScript for sticky items
[6]    JavaScript for zooming images
[7]    JavaScript for sorting function in tables
[8]    Links to other JavaScripts that can be implemented well specially in online help
[9]    Excellent general collections of jQuery-Plug-ins
[10]  A compact tutorial for JavaScript and for jQuery; however this knowledge is not even required to use a ready to use jQuery-Plug-in.

Page 1 from 1
1
#2 Marc Achtelig wrote at Thu, May 19 answer homepage

Hi Diane,

 

Yes, sure you can use scripts in HTML5. Probably you ARE creating WebHelp. Essentially WebHelp just means plain HTML. This is in contrast to compiles help formats like CHM. Most of the scripts won’t work in CHM files due to the outdated technology behind CHM.

 

Cheers,

Marc Achtelig

#1 diane wrote at Wed, May 18 answer

Very nice article, thank you! You state that this relates to uncompiled help systems only, like WebHelp. I am publishing in HTML5, isn't there any way I can incorporate scripts in my help system?

 

Best regards,

diane