Using a Virtual Volume
If you wish to distribute your help system as a single file, cross-platform Virtual Volume, you can place all of your help pages and related sub-folders inside a Virtual Volume instead of a standard help folder. You would still organize your help pages in a Virtual Volume the same way as you would in a standard help folder. Need help creating a Virtual Volume with your help pages? Purchase a UniHelp Component License to receive FREE access to a special UniHelp Edition of HelpLogic for easily creating your UniHelp compatible Virtual Volume! Or purchase a UniHelp Source Code License, which includes a full version of HelpLogic. HelpLogic is the award-winning help authoring solution for Mac OS X and Windows XP/Vista. For complete details, please see the Using FREE HelpLogic page.
Then follow the configuration steps listed in the Configure UniHelp page that requires the following code to be placed in the UniHelpEngine Constructor method (customized to point to your Virtual Volume file):
me.UseVirtualVolume = True
If me.UseVirtualVolume then
me.VVInitialize( "UniHelpGuide.vv" )
Else
me.HelpFolder = GetFolderItem("Help")
End If
Then the only step left is to use the exact same launch code as if you were calling a help file from a standard help folder. In the Action event of your help menu handler or help button you would add the following code to display the UniHelp window (customized to point to the help page folderitem you wish to load):
Dim hlppage As FolderItem
hlppage = UniHelp.HelpFolder.Child("introduction.html")
UniHelp.Run(hlppage)
As of UniHelp 3, the creation of multimedia FileTypes in your project for use with Virtual Volumes is NO LONGER REQUIRED. That was an old requirement from previous UniHelp versions to workaround REALbasic's inability to directly open pictures and media from Virtual Volumes. To help streamline the UniHelp set-up process and improve performance speed, instead of accessing help files from your Virtual Volume in real-time, as of UniHelp 3, when your application launches and initializes UniHelp (in your App.Open event), the entire contents of your Virtual Volume Help are temporarily extracted/copied to the OS temporary folder. This provides UniHelp with very fast access to your help pages while your application is running. This also greatly simplifies the launch code used to call a help page from a Virtual Volume. Now calling a help page from a Virtual Volume uses the exact same launch code as if you were calling a help file from a standard help folder (since technically, you're calling the help page from the temporary folder). Since this is all done in the OS temporary folder, those temporary help files will be automatically deleted when your system regularly cleans/purges its temporary folder.
The copy process from your Virtual Volume to a temporary folder is actually very fast and takes place immediately when your application is launched, so even if you have a LOT of help files, they should all be extracted and ready for use long before a user clicks the Help button.
READ-ONLY DISKS:
REALbasic Virtual Volumes CANNOT be opened from read-only locations such as Mac OS X disk Images, CD-ROMs, DVDs, or locked drives/disks. If you need your application to access help pages from a read-only location, then you should store your helps pages in a standard help folder.
STICK WITH ONE HELP FORMAT:
For best results, use either a standard help folder -OR- a Virtual Volume for your help system, but not both at the same time. Switching from a Virtual Volume to a standard help folder while the UniHelp window is still open may produce incorrect Table of Contents linking when using the Back button.