UHScript Links

What is a UHScript link?

It is a special hyperlink in an HTML web page that, when clicked in UniHelp, will run a specified REALbasic method within your application.

Why would you use a UHScript link?

Since your help pages are accessible within your application via UniHelp, you may find it helpful to trigger REALbasic code within your application based on hyperlinks that a user clicks on. After all, online help is about helping your customer use your application more efficiently. For example, say your application contains a window with a method that checks your web server for the latest version, but one of your customers cannot figure out how to access that window. The customer turns to your application's online help for answers and after performing a search in UniHelp, the customer quickly finds the answer. Besides explaining how to access that particular window, the HTML help page can also include a hyperlink that, when clicked in UniHelp, conveniently launches the method that instantly checks the web server for the latest version.

The syntax for a UHScript link is similar to a "mailto:" hyperlink in standard HTML, except instead of using "mailto:" followed by an e-mail address as the hyperlink, you would use "UHScript:" followed by the name of your method and any parameters you need to pass. For example:

<a href="UHScript:WebLinkRBCode('I%20Love%20UniHelp!')"></a>

would set the clicked link to run the method "WebLinkRBCode", passing the text "I Love UniHelp!" as a string parameter. Notice that the space characters are replaced with the %20 URL encoding -- just like standard hyperlinks, UHScript links must be URL-encoded in order to work in UniHelp 2 and higher.

UniHelp utilizes REALbasic's built-in RBScript to execute UHScript links in real-time. Notice in the example UHScript link, the string parameter is surrounded by apostrophes instead of the usual quotes. Remember to always use apostrophes instead of quotes in the UHScript link so that your code does not break the HTML. UniHelp will convert the apostrophes into quotes on the fly before running the RBScript code.

UHScript Link Example - Run an RB Method with a String Parameter:
<a href="UHScript:WebLinkRBCode('I%20Love%20UniHelp!')"></a>

UHScript Link Example - Run an RB Method (No Parameters):
<a href="UHScript:WebLinkRBCode"></a>

UHScript links do not support raw RB code, so only use this special link type to run existing methods within your application. Call any kind of method within your application, and within that method you can program any kind of events/action you want.

How does UniHelp know where your methods reside in your application? The following line (located in the UniHelpEngine.UniHelpEngine Constructor method) defines the RBScript.Context as a Window Object, so that if your "WebLinkRBCode" method resides in your "MyApp" window, it would be defined for UniHelp with the following setup line:

UHScriptObject = MyApp

Using UHScript links in your HTML help pages is completely optional.

IMPORTANT NOTE: UHScript utilizes the RBScript library, which adds 1 MB to your compiled apps. If you do not want to use this feature and would rather have a smaller compiled app, you can "turn off" UHScript by simply removing the UHScripter class from your REALbasic project and leaving the UniHelpEngine.RunScript method empty. DO NOT delete the UniHelpEngine.RunScript method, just leave it empty to avoid compiling errors.