Context-Sensitive Help generation and Integration Using Adobe Robohelp

Description: In this deliverable I will explain how to configure Adobe Robohelp to generate Context-sensitive help and integrate it with a static page on Yioop!

Introduction

Adobe RoboHelp is another help authoring tool that helps the content writers to generate help in various formats including DotNet help, WebHelp , HTML5 help etc. Robohelp also supports generation and publishing of context-sensitive help  for web applications. This deliverable explains how to install and configure Adobe Robohelp for generating context-sensitive help content to integrate into a Yioop configuration page.

Resources

• Adobe Robohelp can be downloaded from https://www.adobe.com/products/robohelp.html . I will be using a trial version of Robohelp running on Windows.
• Yioop! can be downloaded from https://www.seekquarry.com/?c=main&p=downloads

Context-Sensitive help generation.

I first started by creating a new project in Robohelp. I do this by pressing ctrl+n or by clicking New project on the splash screen.

Then we need to select a template, either we can select an empty template or a default template in this step. Once this step is completed, we can see the newly created project with the contents filled with placeholder content. The structure and the sample content was based on the default template we have selected.

The figure below shows a view of the left hand side pane for Adobe Robohelp. There are advanced options like Skins, Master pages, Screen profiles, etc. Which are used for styling and inheritance for help documents. We will not be using those options for now. However, the header file and MapIds file are something we are going to use in this deliverable.

Creation of Help content

For this demo, I am going to generate Context-Sensitive help content of the Configure Page on Yioop! For a demo, there are three components on the configuration page, which were identified to insert the Context-Sensitive help. The places where help will be inserted is highlighted in the figure below.

For the highlighted components in the configuration page, We will use the help content from the Yioop official documentation at http://www.seekquarry.com/?c=main&p=documentation#installation.

The identified help topics are as below:

• Install & configure 
• Profile settings 
• Advanced settings 
• Crawl-robot setup 

We can create a single chapter into which all these four help topics will be integrated. I called the chapter Install & configure. The project content looks like the below once we have renamed the contained components. I have also removed the unneeded chapters from the project.

I have used the official documentation and used it in the help topics as it is. Now, finally I ended up with four HTML files for the four help topics under the Install & configure chapter.

Alias File and Header files.

We need to maintain information of which dialog box or window maps to which help topic. Header files are the plain text files that carry this information.

We can find the Header files in the Project Organizer under the advanced folder. Robohelp provides a way to export the header files into various formats depending on the programming language used to build the software system.

Alias files, on the other hand, contain a mapping between the support chapters and their respective hyperlink. The names, which identify the chapters, are assigned a help content page in HTML format.

Below is an example of Header file.

	
#define Advanced_Settings1002
	
#define How_to_Search1003
	
#define Search_Results1004
	
#define Crawl_Robot_Setup1008
	
#define Installation_and_configuration1009
	
#define Basic_settings1001
	
#define Performing_and_managing_crawls1000

Below is an example for Alias file.

	
<?xml version="1.0" encoding="utf-8"?>
	
<aliaslist version="1.0">
	
<alias name="Crawl_Robot_Setup" link="1_Install_&amp;_Configure\Windows_used.htm">
	
</alias>
	
<alias name="Advanced_Settings" link="1_Install_&amp;_Configure\Advanced_Settings.htm">
	
</alias>
	
<alias name="Performing_and_managing_crawls" link="Crawl_Management\Performing_and_managing_crawls.htm">
	
</alias>
	
<alias name="Basic_settings" link="1_Install_&amp;_Configure\Basic_settings.htm">
	
</alias>
	
<alias name="Search_Results" link="2_Search_and_User_Interface\Search_Results.htm">
	
</alias>
	
<alias name="How_to_Search" link="2_Search_and_User_Interface\Starting_the_WidgetMax_application.htm">
	
</alias>
	
<alias name="Installation_and_configuration" link="1_Install_&amp;_Configure\Installation_and_configuration.htm">
	
</alias>
	
</aliaslist>
                        

You can see the Alias/Header file file opened in Robohelp editor in figure above.

Generation of Identifiers

There are two ways to generate identifiers for the project in the Alias file. Either we can manually specify identifiers or auto generate identifiers if we already have the help content and most importantly If we decide to generate the content first. There are cases where the Developer might assign Ids to windows/dialogs for linking help content. In this case the developer gives the list of IDs in a header file, which in turn is used by the content author to use in the Alias file. We will use the former scenario in this demo where the ids are auto generated and given to the developer.

The figure above shows the context menu in the Alias file editor. The option Auto Generate is what we will use to auto generate. I have already generated the Identifiers, so you can see the generated Identifiers in the figure above highlighted.

Building and publishing content

Now we are navigating to the Single Source lay out menu in the bottom left corner of Robohelp. We need to select the type of help we would like to generate. Right click on Webhelp and click generate. The dialog box for generation of help content now appears. The figure below shows the same.

We should now click on the Save and Generate. Once we click on this, the help content will be compiled with all the meta data and the build will be completed. 

Once the process completes , we should see the below output in the console window :

Help content Integration with Yioop!

There are two ways to publish the content to the web server on which Yioop! is installed. We can either copy the contents of the CSH output folder to a subdirectory on the web server or we can use the integrated Publish via Ftp tool in the CSH system. For now, we can just copy over the contents to the web server. I have created a subdirectory under Yioop! Directory, and called It CSH. We can now copy all the contents of the output folder to this subdirectory.

Now the output folder is located at http://localhost/yioop. We can hit this directory to test if we can load the help pages. Once loaded the help pages look like in figure below.

The help is displayed in a pop-up and HTML buttons are used to trigger the help pop-ups. In order to integrate the pop-up based help in the configuration page of Yioop, we need to add the hyperlinks that fire the pop-ups. First of all we need to find the View page that displays the configuration page. This is a PHP file "yioop/views/elements/configure_element.php". This is a server side PHP file that dynamically generated the HTML content on the configuration page. We need to include the JavaScript helper file that holds the CSH functions In the page. We do this by linking the "RoboHelp_CSH.js" file in the Yioop HTML source.

The three HTML elements where we need to integrate help buttons are usually titles of the elements. The titles are specified in HTML labels for the concerned attribute.

The labels, which we use to integrate help buttons are :

Directory path configuration - 1001

Toggle Advanced Settings  - 1002

Robot Description -1008

Now we add the function calls beside each of these HTML elements with the snippet below :

Once the integration is complete, the final page looks like figure below.

Finally embedded help looks like figure below. You can also try out the demo by following this demo.