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 namePrototypeDescription, comments
CloseCurrentWindowprocedure window.external.CloseCurrentWindow();Closes the current window (it can prompt end users).
GetGlobalVariablefunction 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.
SetGlobalVariableprocedure 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.
RunHEScriptComprocedure 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]
GetHEScriptComfunction 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]
GoToPageprocedure 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.
HEPrepareFilefunction HEPrepareFile(Path; Operation: Integer)This function is used internally by HTML Executable; do not use it yet.
GetStringfunction GetString(ID)Returns the resource string whose name is given by ID.
ShowPopupprocedure ShowPopup(Name, URL, Width, Height, Top, Left, Param)Opens a new popup window. More information about this function.
ClosePopupprocedure ClosePopup(name)Closes the popup window whose name is given by “name”. More information about this function.
SetPopupPropprocedure 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');
SetUIPropprocedure 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.
StartInternalServerprocedure StartInternalServer()Forces the localbuilt-in server to start. Note that the URL root to the server is stored in the HEBuiltInServerHost global variable.
Utf8ToUnicodefunction Utf8ToUnicode(str)Converts a UTF-8 string to a Unicode string.
UnicodeToUtf8function UnicodeToUtf8(str)Converts a Unicode string to a UTF-8 string.

Examples

  1. To call an HEScript function, you can also 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")

  1. 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.
  1. 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?

© G.D.G. Software 2015. All rights reserved.