HTML Executable Documentation - JavaScript extensions: window.external

JavaScript extensions: window.external

Applies to IE Browser publications only.

HTML Executable features its own script language HEScript which allows you to extend the functionality of your ebooks and publications. Since you can also use JavaScript in your HTML pages, the Dynamic HTML Object Model was extended so you can also control your publication and ebook through JavaScript: some JavaScript “external” commands (a.k.a. methods) are accessible from the window.external object.

Syntax:

window.external.[methodname](...)

List of available window.external methods

Method name	Prototype	Description, comments
CloseCurrentWindow	`procedure window.external.CloseCurrentWindow();`	Closes the current window (it can prompt end users).
GetGlobalVariable	`function window.external.GetGlobalVariable(Name, DefValue)`	Returns the value of the global variable whose name is Name. If the global variable does not exist, the DefValue is returned. Similar to GetGlobalVar HEScript function.
SetGlobalVariable	`procedure SetGlobalVariable(Name, Value; IsStored: WordBool)`	Sets the Value of a global variable whose name is Name. If IsStored is true, the global variable is persistent: its value will be stored and restored the next time the publication is run. Similar to SetGlobalVar HEScript function.
RunHEScriptCom	`procedure RunHEScriptCom(ComLine);`	This function is the most used: it lets you execute an HEScript function or procedure. It is similar to the hescript: protocol, except that you specify the command line via ComLine. Syntax for ComLine: `[HEScript script name].[procedure/function name]
GetHEScriptCom	`function GetHEScriptCom(ComLine, DefValue)`	This function is similar to the previous one except that it calls an HEScript string function and returns its result. It is similar to the hescript: protocol, except that you specify the command line via ComLine and a default value in DefValue if the function is not found. Syntax for ComLine: `[HEScript script name].[procedure/function name]
GoToPage	`procedure GoToPage(URL, Window)`	This function causes the publication to navigate to the URL specified by URL and in the window named by Window. Window should be left to blank.
HEPrepareFile	`function HEPrepareFile(Path; Operation: Integer)`	This function is used internally by HTML Executable; do not use it yet.
GetString	`function GetString(ID)`	Returns the resource string whose name is given by ID.
ShowPopup	`procedure ShowPopup(Name, URL, Width, Height, Top, Left, Param)`	Opens a new popup window. More information about this function.
ClosePopup	`procedure ClosePopup(name)`	Closes the popup window whose name is given by “name”. More information about this function.
SetPopupProp	`procedure SetPopupProp(Name, Value)`	Set a property or invoke a method for the popup window whose name is given by “name”. Available Values: * setfocus: gives the focus to the popup. * bringfront: brings the popup to front. * sendtoback: sends the popup to back. * parentexplicit: makes the popup independent (disables the z-order auto management). It also resets the entire window. Example: `window.external.SetPopupProp('popup1', 'setfocus');`
SetUIProp	`procedure SetUIProp(ID, PropName, PropVal)`	Sets the value of the specified property of a control whose name is given by ID. Similar to SetUIProp HEScript function.
StartInternalServer	`procedure StartInternalServer()`	Forces the local built-in server to start. Note that the URL root to the server is stored in the HEBuiltInServerHost global variable.
Utf8ToUnicode	`function Utf8ToUnicode(str)`	Converts a UTF-8 string to a Unicode string.
UnicodeToUtf8	`function UnicodeToUtf8(str)`	Converts a Unicode string to a UTF-8 string.

Examples

To call an HEScript function from JavaScript

You can use this JavaScript function:

function executecom(sname)
{
window.external.runHEScriptCom(sname);
return 0;
}

For instance, if you want to call the HEScript procedure UserMain.Procedure1, use: javascript:executecom("UserMain.Procedure1") or directly javascript:window.external.RunHEScriptCom("UserMain.Procedure1")

To display a resource string in your HTML pages

Use this code:

document.write(window.external.GetString("[Name]"));

where you replace [Name] by the name of the resource string you want to display.

Working example: we used this script to insert the title of this publication in this HTML page, as you can see below:

document.write(window.external.GetString("SPubTitle"));

Example not available in this online documentation: please run the offline help from HTML Executable to have a working example.

Call an HEScript string function and return its result

With window.external.GetHEScriptCom(ComLine, DefValue)

JavaScript code:

function testRun() {
var s = window.external.GetHEScriptCom('usermain.getit|password1', 'none');
alert(s);
}

It calls this HEScript string function defined in UserMain:

function getit(what: String): String;
begin
Result := MD5OfAString(what);
end;

See these topics also:

Introduction to scripting

How to call HEScript procedures/functions?