Running Hscript Commands from Javascript

Overview

This document describes how to set up and debug html files that control Houdini when viewed through Houdini's integrated web browser. These html files use special JavaScript commands to interact with and control a running Houdini session.

A basic understanding of JavaScript and Hscript is assumed. To learn more about JavaScript, there are many tutorials available online. Note that JavaScript is also known as ECMAScript, and you're more likely to find information about the core language itself by searching for ECMAScript. To learn more about Hscript, see the scripting reference or the command index.

Setup

You must add the following line to the html document:

<script language="JavaScript" src="resource:///res/RunHCommand.js"></script>

This line will include an internal JavaScript file that defines the RunHCommand() JavaScript function. The URL resource:///res/RunHCommand.js points to a file inside Houdini's web browser's directory hierarchy.

Also, to use the example code in the cookbook, you will need to add this line to the html document:

<script language="JavaScript" src="HB.js"></script>

The HB.js defines a small library of JavaScript commands used by the cookbook examples. You may use this library as a starting point for your own JavaScript libraries. Note that you will need to copy the contents of HB.js to the same directory as your html document.

Running Hscript Commands

The JavaScript command RunHCommand() takes an Hscript command in the form of a string, executes the command in Houdini, and returns the result of the command as a string.

Debugging Tips

Houdini's integrated web browser, hbrowser, does not alert you when there are JavaScript errors in your program. While it is possible to use a regular web browser to find your JavaScript errors, it is very inconvenient to do so. The RunHCommand() function is not defined outside hbrowser, and even if you write your own version for testing, the result of your function will not be the same as the result of the real function.

However, because hbrowser is based off the Mozilla browser, it is possible to run Hscript commands from a full Mozilla browser and use Mozilla's debugging tools. The part of hbrowser that handles calls to RunHCommand() is implemented as a Mozilla component, and that component can be installed as part of Mozilla. You can download Mozilla from www.mozilla.org.

To copy the necessary component from hbrowser to Mozilla, you'll need to do the following, where $HFS is the directory where Houdini is installed and $MOZ is the directory where Mozilla is installed:

  1. Exit Mozilla
  2. Copy $HFS/mozilla/components/libHoudiniConnection.dll (libHoudiniConnection.so on unix) to $MOZ/components/.
  3. Copy $HFS/mozilla/components/IHoudiniConnection.xpt to $MOZ/components/.
  4. Copy $HFS/mozilla/res/RunHCommand.js to $MOZ/res/.

Before you restart Mozilla to test your code, however, you need to ensure that Houdini is waiting for commands from the Houdini connection component. This component communicates to Houdini using Houdini ports, just like the hconnect program does. When Houdini's help browser starts up, Houdini opens a port so it can listen to commands from hbrowser. When controlling Houdini from Mozilla for debugging, it is necessary for Houdini to have opened a port and be waiting to run commands. The easiest way to open this port is to first launch hbrowser. So, to debug your script using Mozilla,

  1. Start Houdini.
  2. Open the Help browser in Houdini.
  3. Load your page into Mozilla. You can view JavaScript errors using the JavaScript console.

You can also step through you JavaScript program using the JavaScript debugger (Venkman). If the JavaScript debugger is not installed in your version of Mozilla, you can download it from here.

Examples

For examples, see the cookbook.