Module: userInterface

Implementation for Nashorn and CapeCode of the module supporting accessor interaction through a user interface. The Server object starts a server that accepts web socket connections and HTTP GET and POST requests.

This module defines one class, UserInterface. After constructing an instance of UserInterface (using new), you can request that the user interface display HTML that you provide using the display() function. Whenever display() is called, whatever was previously displayed is replaced with your content in the user interface.

You can also specify resources that the HTML references (such as images) by using the addResource() function. You should call this before providing HTML that requires those resources. Note that updating a resource with the same name will not normally result in the web page being updated because user interfaces normally cache such resources. If HTML content refers to a resource that has already been loaded (or more precisely, that has the same name as a resource that has already been loaded), then the user interface will not load the resource again, but rather will use the previous version. You can force the user interface to reload a resource by augmenting the name with parameters (which will be ignored). For example, if you have a resource named "image.jpg" that you wish to update it, then you can specify HTML like this:

<img src="image.jpg?count=n"/>

where n is a unique integer not previously seen by the user interface. This will force the user interface to go back to the server to retrieve the resource.

You can also add listeners for data sent by the user interface using POST using the addListener() function. So your HTML can include forms and buttons, for example, that will POST JSON data.

You can specify optional header content when you construct the UserInterface object. This is a good place to include scripts. The HTML content provided to UserInterface.display() can also include scripts. Those scripts can invoke functions defined in the header or reference variables defined in the header.

Scripts in the header can invoke a require(module) function to use any module supported by the browser host. The 'util.js' module is automatically included, so there is no need to explicitly require it. For example, to use the web-socket-client module, your script could include:

var ws = require('web-socket-client.js');

The way this module works is that it starts a web server that accepts websocket connections and HTTP GET and POST requests, and then it invokes the system's default browser and points it at that web server. The server provides HTML that contains a script to connect to the server using a websocket. It then listens for messages on that websocket, and when it receives them, it displays their contents (HTML) on the web page, replacing whatever was there before. Hence, a highly dynamic stream of pages can be provided.

The websocket can also accept incoming JSON data, in which case the UserInterface object will emit a 'message' event.

Version:
  • $$Id$$
Author:
  • Edward A. Lee
Source:

Methods

(static) UserInterface(options, header, content)

Constructor for a UserInterface server.

The options argument is a JSON object containing the following optional fields:

  • hostInterface: The IP address or name of the local interface for the server to listen on. This defaults to "localhost", but if the host machine has more than one network interface, e.g. an Ethernet and WiFi interface, then you may need to specifically specify the IP address of that interface here.
  • port: The port on which to listen for connections (the default is 80, which is the default HTTP port).

The optional header argument specifies any text to include in the header of the web page that is created.

The web page is opened the first time display() is called.

This subclasses EventEmitter, emitting events 'listening' and 'connection'. A typical usage pattern looks like this:

    var browser = new require('browser').UserInterface({'port':8082});
    browser.display('
Hello
');
    setTimeout(function() {
       browser.display('
World!
');
    }, 5000);
    browser.stop();

This displays "Hello" and then changes it to "World!" after 5 seconds. The UserInterface is an event emitter, emitting events 'listening' and 'connection'.

Parameters:
Name Type Description
options

The port and hostInterface options.
header

HTML to include in the page header.
content

HTML content to include in the page.
Source:

(inner) createTemplatePage()

Create the template page, which pulls in jquery, defines the require() function, and includes the util module. It uses the browsers WebSocket to open a socket to the server to listen for updates to the content. And it constructs the default page using the specified header and content. Finally, it launches the browser.

Source: