Adobe AIR Help in RoboHelp 9 and above

 

 

What's covered?

AIR help is a form of help from Adobe using .AIR technology. Whilst AIR Help remains an output offered within RoboHelp, it is no longer being developed. I would not recommend starting any new projects with this output.

 

What's new in RoboHelp 9

There have been no changes to AIR Help since RoboHelp 9.

Creating AIR help

Topics are created in the same way as any other output and that is outside the scope of this article. What we will do here is look at how you generate the outputs.

General Settings

 

Field

Description

Output Type

Select one of the four options.

Option

Description

Adobe AIR Application

Creates an AIR file for local installation.

Browser Based Help

Creates browser based air help.

AIR Application and Browser Based Help

Creates both the above.

Help Content Only

Creates the content only where your developers will be creating their own viewer. Selecting this option will disable the Template page.

Output Location - AIR File

Where you will generate the AIR file.

If you are generating both forms of AIR help, you might find it easier if you first create a folder under the SSL folder in Windows Explorer. In the layout select that folder for both. RoboHelp will create separate folders within your chosen folder.

Output Location - Start Page

Where you will generate the browser based help and the name of the start page.

Help Title

What you want to appear on the title bar of the help and the name that will appear in Program Files. It must be unique to each project and not be a name that might be used by someone else, such as "Help". I suggest something like Company A Product X Help. While this is the name that will appear in Program Files, it is not what the Auto Update uses when looking for previous versions of the help. If your company name and product name change and you alter the Help Title to Company B Product Y Help, the old version will still get removed and be replaced by the new version.

Version / Help ID

Whatever you want but they combine to create a unique key for each version. Do not change the Help ID, just increment the version number each time you release a new build. The combination of those two fields is the key to the mechanism that tells the installed help that a later version is available.

Digital Certificate

Adobe .AIR requires a digital certificate. Digital signing assures users that the help has not been maliciously altered and identifies your organisation as the publisher.

For internal use it does not matter whether or not it is a signed certificate and for testing it is easy to create a certificate using the screen accessed from the Create button. Below is a simple diagram showing how digital signatures work.

You will probably want to use a signed certificate for your customers. You can purchase digital signatures from recognised authorities such as VeriSign or Thawte. Don't worry too much about this aspect. Normally your IT department will deal with it.

There is a PDF with more information on this on Verisign's site.

If it helps, this is how I got it working using a Verisign certificate.

  1. Get the .PVK and .SPC files, probably from your developers, and put them in a folder.
  2. Get the pvk2pfx.exe file from Microsoft and put that in the same folder. See the instructions and link on Verisign's site. Click here.
  3. Either follow those instructions or save the file to the same location as the .PVK and .SPC files and run a batch file, again from the same folder. The contents of the batch file will be as below. Just change the words in blue to your file names and password.

    pvk2pfx -pvk myprivatekey.pvk -spc mycredentials.spc -pfx mypfxfile.pfx /po mypassword
  4. A PFX file will be created in the same folder. This file is not yet ready to use.
  5. Double click the PFX file to start the import wizard.
  6. In the second page, make sure you tick the Mark this key as exportable option.

  7. In the next page, I used the automatic option.
  8. Continue and you should get an Import Successful message.
  9. Open Internet Explorer and go to Tools > Internet Options > Content > Certificates.
  10. Select the certificate you just imported and select Export. (Yes you read that correctly!)
  11. Follow the wizard making sure you select Yes, Export the Private Key.
  12. In the next page select the Personal Information Exchange option and make sure you tick Include all certificates and Delete the private key.

  13. Continue through the wizard until prompted to save the PFX file being created. Either overwrite the one created earlier or save the file to a new location.
  14. Browse to the new file from the AIR wizard.

If the certificate used is changed in an upgrade of the help, it will be seen as a new installation rather than an upgrade. That would require the old help to be uninstalled first or the new help to be installed to a new folder. Either way any comments would be lost.

To avoid that, you will need to refer your developers to Adobe's instructions for changing the certificate. Click here.

Password

Enter your password for the certificate. Tick the Remember box if required. The password is mandatory.

Include Timestamp

If left blank it will not be possible to install the .AIR file after the certificate has expired. If ticked then the timestamp is included and it will be possible to install it, notwithstanding that the certificate has expired.

Program Menu Folder

By default, the help will be installed in Program Files in a sub-folder with the name of the help file.

If you want to specify a higher level folder within Program Files to which the help will be installed, enter the name of the sub-folder here.

For example, you might want all your company's help files to be entered in a folder named Company A. If you enter Company A here and the help file is My Help, the help will be installed in Program Files/Company A/My Help

 

Content Settings

These settings are the same as for any other online help output. Select as required.

 

The Wizard - Template Settings

 

Field / Button

Description

Template

Select the required template. See Adobe AIR Help Templates and Skins.

Skin

Select the required skin. See Adobe AIR Help Templates and Skins.

Copyright

Your copyright notice. Appears in Help | About.

Description

A description of the help. Appears in Help | About.

Favicon

This new field in RoboHelp 9 allows you to add your own favicon that will appear in the title bar of the viewer.

Width / Height

The default size of the locally installed browser. RoboHelp 9 and above produced AIR help will retain the viewer size that the user sets by dragging the bottom right corner.

Specify Branding Options

Click Select to access the Branding Options screen.

Your branding icon is displayed in locations predefined by the operating system, such as the desktop icon, the title bar and so on. It needs to be in PNG format in each of the four sizes and should look good in both 16 and 32 bit colour modes. If you do not specifiy an icon, the operating system defaults will be used.

You can also specify a 32 X 32 icon for a company logo to appear in the top-right corner of the help viewer.

 

Branding Options

 

Field / Button

Description

Icon Images / Logo

Browse to the required images.

Text

Insert whatever you want, within reason!

Next

Toggles displaying the Icon Images and the Company Logo.

View Settings

 

Field / Button

Description

Search Fields

These settings are the same as for any other online help output. Select as required.

"Show context in Search Results" is not available in all the templates.

Enable Auto Update

Tick this box if you want auto-updating to be enabled.

You can specify a network location or a web location for the XML and AIR files that will be created when you generate an output with this option ticked.

With this option enabled, when you update the help you increment the version number in General Settings but you do not update the Help ID. When the user opens the help it will look in the specified location and if it finds a higher version for the same ID, the user will be prompted to install the update.

When a user is prompted that an update is available, they will need local admin rights to install it. If your users are in an organisation that does not give local admin rights to end users, then the IT Admin will need to install the update, either on each machine or by pushing it. If all your users are in such an environment, then you would not use auto update, instead you would send the necessary update to the IT Admin.

Consider who you want to get the update.

If your product is at Version 1 and the help is about some updates that Version 1 users are entitled to get free, you will want them to have the revised help. When your product goes to Version 2 you have a situation where you want Version 1 customers to continue getting any updates to which they are entitled and you will want Version 2 customers to get their updates. What you don't want is Version 1 customers getting Version 2 help via an auto update. The problem is the AIR help will simply see the highest version number and offer that as an update.

The solution is quite straightforward. You use different locations for the updates for each version of your software.

IF YOU USE A CONFIGURATION FILE

Version 1 customers will have a configuration file that points to Location A. When you update someone to Version 2, you install a new configuration file that points to Location B. Change the Version ID but not the Help ID. That will allow customers to update their help and retain their comments, favourites and suchlike while telling the help to look in a different location for auto updates. Version 1 customers will not have that updated configuration file so their help will continue to look in the old location.

The first release of your Version 2 help will be installed manually, typically as part of the installation of the application update and after that auto update will be looking at the new location.

IF YOU DO NOT USE A CONFIGURATION FILE

The logic is the same but you specify the new location in this field. The AIR help for Version 1 customers will continue to look for updates wherever you specified for that version. When your Version 2 software is installed, the help for Version 2 will be installed as part of that routine, not as an auto update and then it will look in the new location for auto updates.

MAINTAINING BOTH

If you maintain the help for old versions as well as the current version, you simply put the updates in their respective locations. Version 1 customers will not be offered Version 2 help as it is in a different location.

Add Resources

Tick to add links or RSS feeds that you want to be available to the user. Users can add their own links and feeds.

Show Online Content

If you want users to use online content when a connection is available and local content at other times, tick this option and enter the URL for the online content.

UPDATE 12th March 2012 - In theory you would use the "AIR Help Application and Browser Based Help" option to generate the required outputs and then publish the Browser Based Help to the location you specify. However, a bug has been identified and if you do this you will find that when a user clicks a breadcrumb link while using the online help, they will get a Page Not Found error. Instead generate WebHelp and publish that to the location specified.

 

Server Settings

 

If you selected to generate browser based AIR help, the Server settings will be enabled. Define the location of the published output in the same way as when producing webhhelp.

Collaboration

 

Field / Button

Description

Enable Topic Rating

RoboHelp 9 introduced Topic Rating to allow users to apply a star rating. Initially the user will see their own rating but when they Send / Receive comments, the rating will be averaged.

Enable Commenting

Comments can be made by end users and by reviewers. See the Comments section in Adobe AIR Help.

Enable Comment Moderation

RoboHelp 9 introduced comment moderation.

Set Location for Comments and Topic Ratings

Comments and Topic Ratings can be stored on a network folder or on RoboHelp Server.

Network Folder

To enable users to share comments, enter a network folder using the server name, not the mapping letter, otherwise leave the path blank. The same folder is used for storing topic ratings.

The Browse button does not see mapped network drives as other users might not have the same mapping. However, you can type in the path using the server name and that will work.

Typically you only want users within one company to see comments made by users in that company.

With RoboHelp 8 having to enter a server name created a problem as the server name and path would be different at each location. There was a workaround but RoboHelp 9 introduced a configuration file. Using that, the network folder can be defined at each location. See Configuration File Path below.

Network Folder

The default network location.

This can be left blank and defined in the configuration file.

Set moderator password

Enter the required password. Any user with this password can moderate. If you require greater control, consider using RoboHelp Server.

Mark new comments as...

This can be set to Pending or Approved.

A Pending comment can only be seen by the person who created it and a moderator.

When a comment has been approved, other users will see it the next time they click Send / Receive.

RoboHelp Server

Integration with RoboHelp Server was introduced in RoboHelp 9. The features are described below. Here you set the path.

Configuration File Path

RoboHelp 9 introduced the configuration file allowing many of the options to be configured specifically for a site. The options are described below.

The path entered here is where the installed help will look for the configuration file, not where it will be created when you generate the .AIR file. The configuration file can be named as you wish but I recommend that you call it configuration.xml to avoid confusion.

When you ship the .AIR file, the configuration file must be saved to the location you define here.

 

The LNG File

You can customise many of the terms that appear in AIR help by accessing the LNG file and scrolling down to the Adobe AIR section.

What do I do with the output(s)?

Locally installed AIR help

First check it on your own PC! It is important that you understand that the AIR file is not the help itself in the way that a CHM file is, it is an installer.

With the AIR runtime installed, you simply double click the AIR file. and you will see a window telling you the file is being prepared and then you will see a certificate dialog.

 

 

Click Install to see the default install path. The installer will add a folder for the name you define in the Help Title. The program folders and files installed are pretty much the same as a webhelp output but like any program, the end user does not see that. All they have to know is that installation is as quick and easy as any program and they just click a shortcut.

 

 

That's it. The help will open as that option was ticked. If you are happy the help is functioning correctly, pass the AIR file to your developers. If required they can include the installation of the AIR Runtime (see More Information below) and the AIR help with their normal installation routine. In an enterprise organisation the local IT Admin can push installation rather than having to go to each machine and install it manually.

Browser based AIR help

Deliver the output to your developers in the same way that you would WebHelp. In other words, give them all the files in the output folder. I suggest you zip them up and deliver the zip file.

Help content only

Deliver the file to the developers. If you are working with this output, it will be at their request and they will know what to do with the file.

More information

Your developers might find this page on Adobe's site useful. It contains the information they will need about installing an AIR application from the desktop or a web page.

Click here for the AIR runtime distribution FAQs page.

This page contains information about distributing the AIR Runtime and enables you to apply for a licence.

Merged AIR Help

Contrary to what was previously stated here, both Browser Based AIR Help and Desktop (local) AIR Help can be merged.

Calling the Help

Browser Based AIR Help

This is called in the same way as WebHelp. See Calling WebHelp if you need further information on that.

Locally Installed AIR Help

If you simply want to open the help, create a link to the exe file in Program Files.

For context sensitive help, Adobe provide the AIR Help API for many languages including JAVA, VC.NET, CS.NET, VB, VB.NET. Search in the help for "Call a context-sensitive Help function for AIR Help".

If that does not meet your needs, see this section in the RoboHelp 8 version of this article where further information is provided.

For context sensitive help written in any other language, your developers will have create their own call to the exe followed by the parameters. In this post, Timothy Haagenson has detailed what he found. The details are repeated below and in case the forum is not available at any time, here's a PDF of the full thread.

Calling AIR Help from an AIR application

Praful Jain of Adobe posted the following in this thread. (Click here for a PDF of the thread.)


As specified by other people here in the forum, it is certainly possible to call a CSH AIR help from any AIR application. Please check this forum post. (Click here for a PDF of the thread.)

You need to know your AIR Help application ID, and the publisher ID.

Application ID is the one which was specified in the AIR SSL dialog in RoboHelp 8 AIR SSL dialog (Help ID).

The publisher ID for an installed application can be found in the META-INF/AIR/publisherid file within the application install directory. This Publisher ID is generated using the digital certificate provided while generating the AIR Help in AIR SSL dialog.

Once Application ID, and Publisher ID are known to the developer, he/she can call the AIR help by using the Following Flex code

private function invocarAirHelp(tema:String):void {
var appID:String = "abc";
var pubID:String = "ashfksdhfkjsdfk.1";
var mgr:ProductManager = new ProductManager("airappinstaller");
mgr.launch("-launch " + appID + " " + pubID + " -- -csh mapnumber 1");
}


RoboHelp Server Features

RoboHelp Server can be used to improve the moderation functionality and to store comments. Neither locally installed AIR help nor browser based AIR help can be run from RoboHelp Server so the analytic features are not available.

Authenticated Logon

To send and receive comments, users will need to log on and this can be done using various methods including the commonly used LDAP.

Anyone with Administrator privileges will be able to moderate comments. This gives greater control over moderation as without RoboHelp Server anyone with the required password can moderate

Anonymous Commenting

If permitted, users can post comments so that their user name is not revealed to other users. Moderators will be able to track who posted.

Comment Store

The server can be used to store comments and topic ratings in the path defined when creating the .AIR file.

The Configuration File

The file created will contain all the parameters listed on the left but with no settings. Any settings here will override what is in the .AIR file so you either need to define all the settings or delete all except those where different settings are required at different locations.

Example

You may have set up AutoUpdate as enabled but have some sites where users will not have an internet connection or do not have admin rights enabling them to install the update. If that is the only parameter you want to be set locally, then delete all the others and enter autoupdate="no".

Alternatively, supply the file to the local administrator with instructions and let them determine what they want enabled or disabled and the paths to be used.

  <?xml version="1.0" encoding="utf-8" ?>

 

  <

 

config topicrating=""

Set to "yes" if users can rate topics.
Set to "no" to not allow.

marknewcommentsaspending=""

Specify whether new comments should be accepted without moderation.

commentsync=""

Set to "yes" to enable commenting or "no" to disable commenting.

updatecommentlocation=""

If there is an operating system specific folder defined in the next three fields, that will be used. Otherwise the path here will be used.

windowsupdatecommentlocation=""

Specify a central location of choice for storing and syncing comments on a Windows system.

macupdatecommentlocation=""

Specify a central location of choice for storing and syncing comments on a Mac system.

linuxupdatecommentlocation=""

Specify a central location of choice for storing and syncing comments on a Linux system.

autoupdate=""

Specify whether or not auto-update is enabled.

windowsupdatexmllocation=""

Specify a location to store the auto-update XML file on a Windows system.

macupdatexmllocation=""

Specify a location to store the auto-update XML file on a Mac system.

linuxupdatexmllocation=""

Specify a location to store the auto-update XML file on a Linux system.

logoimage=""

Enter the path for the company logo that appears top right in the help.


The branding icons cannot be changed through this configuration file.

companytext=""

Enter the company name that you want to appear bottom left. By default in the SSL, this reads "Powered by RoboHelp".

/>

 

Donations

If you find the information and tutorials on my site save you time figuring it out for yourself and help improve what you produce, please consider making a small donation.

Topic Revisions

Date

Changes to this page

05 Sep 2016

Note added cautioning against creating new AIR Help outputs.

14 Jan 2014

Minor changes as page covers all versions from RoboHelp 9.

16 Dec 2012

Updated to cover "no changes made to RoboHelp 10".

23 Apr 2012

commentsync="" line amended to remove default value.

12 Mar 2012

Fix added for airplane help.

05 Mar 2012

Updated re airplane help.

23 Nov 2011

Instructions for auto update revised to cover when to use auto update.

01 Oct 2011

Instructions for auto update revised to cover better how help for multiple versions of the software can be supported.

24 Sep 2011

Instructions for changing the digital certificate added.

30 Jun 2011

Merging AIR Help section amended to cover merging of desktop AIR help.

13 May 2011

Branding icons reworded. Typos corrected.

20 Apr 2011

Praful Jain's post re airplane help added to Show Online Content.

26 Mar 2011

New Topic