Requirements

Prerequisite knowledge

To follow this article, you should have a basic understanding of:

  • Creating projects and generating output from RoboHelp

User level

All

RoboHelp uses the Adobe AIR technology to output content as AIR Help. This article takes a close look at how you generate AIR Help output from RoboHelp. Topic creation is outside the scope of this article as topics are created in the same way as in any other output.

Configure the Adobe AIR SSL

The Adobe AIR SSL provides a large number of settings to configure the output according to your requirements. Selecting the output type is key because the three primary output types— Adobe AIR Application, Browser Based Help, and Help Content Only—vary significantly in the functionality that they offer and the way in which they are distributed.

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 for use in viewers created by your developers. Selecting this option disables the Template page.

Output Location - AIR File

The location of the AIR file that'll be generated.

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

The location of the browser-based Help and the name of the start page.

Help Title

What you want to display 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 organization 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, which is accessed via 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 recognized 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. 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 select Include all certificates and Delete the private key.

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

Password

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

Include Timestamp

If you leave this blank, you can't install the .AIR file after the certificate has expired. If you select this option, 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 subfolder 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 those for any other online Help output. Select as required.

Template settings

Field / Button

Description

Template

Select the required template.

You can find more information about templates on my site. Click here.

Skin

Select the required skin.

You can find more information about skins on my site. Click here.

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-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. You can specify all of the following icon sizes:

  • 128 X 128
  • 48 X 48
  • 32 X 32
  • 16 X 16

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 presentable in both 16- and 32-bit color modes. If you do not specify your own icon, the operating system defaults will be used. You can also specify a 32 X 32 image for a company logo to appear in the top-right corner of the Help.

Branding options

Field / Button

Description

Icon Images/Logo

Browse to the required images.

Text

Insert whatever you want, within reason!

Next

Toggles displaying Icon Images and Company Logo options.

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

Select 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 output with this option selected.

When you update the Help with this option enabled, 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.

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 likely want them to have the revised Help. In that scenario, change just the Help version.
If your new Help is for Version 2, you would not want Version 1 customers to install the new Help. In this scenario, change the Help ID and start the numbering again. That will not remove the earlier version, your developers will need to ensure that the program upgrade not only uninstalls the old version of the program, it must also uninstall the old Help as part of that routine.

Add Resources

Select 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, select this option and enter the URL for the online content.

This does mean that if users need to access online content at different locations because it has to be behind a firewall, you need to generate an AIR file for each location that has to be specified.

Click here to see Tulika Goel's blog on airplane Help.

Do the following steps to have online/offline support in AIR Help:

  1. Open the project and click the Adobe AIR SSL.
  2. Select Adobe AIR Application in the output type.
  3. In the Collaboration page, check the Show Online Content check box and add the server URL where you want to host the browser -based Help. Let's say the server URL is http://adobe/browserbased/
  4. Click Save and Generate and this will generate the .air file. As of now, online content is not present on the server so AIR will always show offline content.
  5. Now generate browser-based Help output using the Adobe AIR SSL and copy or publish the output folder to the specified server location.
  6. Try to open the server URL (http://adobe/browserbased/ in this case) in the browser to see if the online Help is indeed accessible or not.
  7. Once you are able to see the online browser-based Help, you can open the local AIR Help file and it should start showing the online content automatically.

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 WebHelp.

Collaboration settings

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 that the file is being prepared and then you will see a certificate dialog box.

Field / Button

Description

Enable Topic Rating

RoboHelp 9 introduces topic rating to allow users to apply a star rating. Initially, users will see their own rating but when they send or receive comments, the rating will be averaged.

Enable Commenting

Comments can be made by end users and by reviewers. Select this option to enable commenting.

Enable Comment Moderation

RoboHelp 9 introduces comment moderation.

Set Location for Comments and Topic Ratings

Comments and topic ratings can be stored in 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 has 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 always 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 introduces 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.

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 that the file is being prepared and then you will see a certificate dialog box.

Click Install to see the default installation 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 in 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 selected. If you think that the Help is functioning correctly, pass the AIR file to your developers.

Browser-based AIR Help

Deliver the output to your developers in the same way that you deliver 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

Browser- based AIR Help can be merged in the same way as WebHelp. Locally installed AIR Help cannot 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 provides the AIR Help API for many languages including JAVA, VC.NET, CS.NET, VB, and 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 Adobe AIR Help in RoboHelp 8 article on my site where further information is provided.

Calling AIR Help from an AIR application

Praful Jain of Adobe posted the following.

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.

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

Application ID is the one that was specified in the AIR SSL dialog box 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 the AIR SSL dialog box.

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 comments.

Anonymous commenting

If permitted, users can post comments without revealing their user names 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 configuration file is created in the same location as the .AIR file you generate. At each location where different settings are required, the file must be saved in the location specified when you create the .AIR 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 to 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="no"

Notwithstanding the name of this parameter, set to "yes" to enable commenting or "no" to disable commenting.

updatecommentlocation=""

If there is an OS-specific folder defined in the next three fields, that folder 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".

/>

 

Where to go from here

There are further articles on Peter Grainge's site describing AIR Help from the user perspective and the templates and skins that can be used. They can all be accessed from www.grainge.org/pages/authoring/air/air.htm