Adobe AIR Help in RoboHelp 9
Created
9 May 2011
Requirements
Prerequisite knowledge
To follow this article, you should have a basic understanding of:
- Creating projects and generating output from RoboHelp
User level
All
Required products
- RoboHelp 9 (Download trial)
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.
|
||||||||||
| 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.
|
||||||||||
| 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:
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. |
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:
|
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.
|
||||||
| 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. |
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.
|
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
