Star API Usage

Interfaces provided by JS-Star can be accessed using the global object __star. This section lists the provided public interfaces.

Bootstrap/Shut Down

__star.boot()

starts JS-Star’s bootstrapping process. This method should be called after the DOM is ready (i.e. document.getElementById works).

__star.shutDown()

Removes all infotrons and cleans them up by calling their _onDestruct methods (InfotronDoc has details).

At the end of this process the shutdown event for JS-Star is triggered (details down below).

Infotron Creation/Removal

__star.addInfotron(DOM node id, blueprint UUID, properties)

Allows an existing DOM node to become an instance of a specified blueprint. A set of properties can be provided for parameterization.

The method returns false if the infotron could not be immediately constructed because the specified blueprint was not found. If the blueprint is found, the method returns an array of length two where the first item is an array of input terminals and the second item is an array of output terminals that belong to the infotron.

The DOM node id becomes the id of the infotron

The following sample code attempts to instantiate a DOM node with the id “timer1” as an instance of the blueprint with the specified UUID (~6B5EAB0E6AD4483e84D3D5F1- 4C8AEE7). It also passes in the “timeout” property of value 1000:

\_\_star.addInfotron(“timer1”, “~6B5EAB0E6AD4483e84D3D5EF14C8AEE7”, {“timeout” : 1000});

__star.removeInfotron(infotron id)

Triggers the _onDestruct method (details in InfotronDoc) on the infotron and removes it from the domain.

The following sample code removes the infotron associated with the id “timer1”:

\_\_star.removeInfotron(“timer1”);

Terminal Creation

__star.addOterm(infotron id, ouput terminal name )

Creates an output terminal for an infotron and returns a unique identifier that can be passed into the connectTerminals method.

The following sample code creates an output terminal named timeout_event” for the infotron “timer1”:

\_\_star.addOterm(“timer1”, “timeout_event”);

__star.addIterm(infotron id, input terminal id)

Creates an input terminal for an infotron and returns a unique identifier that can be passed into the connectTerminals method.

The following sample code creates an input terminal named “trigger” on the infotron “alert1”:

\_\_star.addIterm(“alert1”, “trigger”);

Channel Creation/Removal

__star.connectTerminals(infotron id and output terminal pair, infotron id and input terminal pair)

Allows you to programmatically connect two terminals with a channel.

The following sample code connects the output terminal “timeout_event” on infotron “timer1” to the input terminal “trigger” on infotron “alert1”:

\_\_star.connectTerminals([“timer1”, “timeout_event”],

                                         [“alert1”, “trigger”]);`

__star.disconnectTerminals(infotron id and output terminal pair, infotron id and input terminal pair)

Allows you to programmatically disconnect a channel connecting two terminals.

The following sample code disconnects one of the channels connecting the output terminal “timeout_event” on infotron “timer1” and the input terminal “trigger” on infotron “alert1”:

\_\_star.disconnectTerminals([“timer1”, “timeout_event”], [“alert1”, “trigger”]);

Message Passing

__star.queueMessage(infotron id, input terminal name, message)

Queues up a message directly into an input terminal. The following sample code injects a message (an integer value of 1) into the input terminal “trigger” on infotron “alert1”:

\_\_star.queueMessage(“alert1”, “trigger”, 1);

__star.receiveMessage(input terminal name, message)

Analogous to the queueMessage method, except that it is intended for use by a domain.

The following sample code routes a message (an integer value of 2) to whichever input terminal connected to the “%from_parent” input terminal of the domain:

\_\_star.receiveMessage(“%from_parent”, 1);

__star.deliverMessage(reference of the sending domain, output terminal name, message)

Delivers a message to an output terminal of a domain.

The following sample code routes a message (an integer value of 3) to the output terminal “timeout_event” that belongs to the domain contained within the window/frame referenced by the variable “ref”:

\_\_star.deliverMessage(ref, “timeout_event”, 3);

__star.allowMessagingToChild(child reference, input terminals exposed by the child, output terminals exposed by the child )

Called by a child domain that wishes to alert the parent that it is ready to receive messages.

The first argument to the method is the reference to the window/frame the child infotron resides in. The second and third arguments to the method are arrays of input and output terminal names of the child infotron:

\_\_star.allowMessagingToChild(__w, [“trigger”] , [“timeout_event”]);

Event Listening/Dispatching

__star.addEventListener(event name, function)

Registers a callback function for any of the events triggered by JS-Star.

The following samplecode registers a callback function referenced by the variable func for the event “bpmiss”:

\_\_star.addEventListener(“bpmiss”, func);

__star.dispatchEvent(event_name, context)

Artificially dispatches any of the above-mentioned events so as to invoke all of the registered callback functions.

The following sample code dispatches the “shutdown” event. No context is provided, as the “shutdown” event does not normally provide any context:

\_\_star.dispatchEvent({type:”shutdown”});

Event Details

The function signature for the callback takes a single argument, which is an object literal with two members: “type” and “context”.

The “type” member will contain a string denoting one of the above mentioned event types, and “context” will contain event specific data (details to follow).

bpmiss

Triggered when JS-Star tries to deliver a message to an infotron that is yet to be constructed because its blueprint was not found in memory. The “context” member is an array containing the id of the infotron that triggered the event and the UUID of the missing blueprint as the first and second items respectively.

bpload

Triggered when a new blueprint is loaded into memory via the function BLUEPRINT. The “context” member is an object literal with the members “name”, “iterms”, “oterms” and “uuid” containing the name of the blueprint, array of inputlength terminal2. names,The anfirst arrayitem of output terminal names, andis the UUID of the blueprintblueprint. respectively.The second item is an object literal specified as the second argument to the BLUEPRINT function.

afterbpload

Triggered after a new blueprint is loaded into memory via the function BLUEPRINT and all infotrons that were delayed construction have been constructed. The “context” member is an object literal with the members “name”, “iterms”, “oterms” and “uuid” containing the name of the blueprint, array of input terminal names, an array of output terminal names, and the UUID of the blueprint respectively.

boot

Triggered right before the infotrons start to get constructed as part of the __star.boot method call. The “context” member is the reference to the frame/window object in which JS-Star resides.

afterboot

Triggered right after all the infotrons are constructed as part of the __star.boot method call. The “context” member is set to null.

shutdown

Triggered after all the infotrons have been destructed as part of the __star.shutDown method call. The “context” member is set to null.