JSSCxml API

Constructor

new SCxml(mixed source, Element anchor, Object data, boolean interpretASAP)

returns an interpreter instance, attempts to retrieve and parse the source, attaches to the supplied anchor, and starts running as soon as possible if interpretASAP is true.

source
Required
Can be a URL, a Document, a File or an SCXML source string. If it is a string starting with "<", JSSC will try to interpret it as SCXML source code. If it is a URL string, JSSC will send an HTTP request to retrieve it, subject to the usual Cross-Domain restrictions. If source is an instance of Document, JSSC will simply use it (note that the Document itself, not a copy, will be used). If it is a File, JSSC will try to read it and parse it as SCXML source code.
anchor
Default: special
If you provide an Element here, the interpreter will “attach” to that Element (most importantly, DOM Events sent by the interpreter will be targetted at that Element). If you give a falsy value to this argument, JSSC will create an <scxml> element to use as this interpreter's anchor, and append it to the HTML document's <head>. Note that the anchor Element will have an interpreter property pointing to the interpreter instance.
data
Default: null
Must be an Object. That Object's properties will be available to JavaScript code within the SC, e.g. in expr attribute values and <script> content. It is the recommended way to include libraries and share objects with the SC.
interpretASAP
Default: false
If this is true, the interpreter will start running as soon as possible, i.e. at the time its readyState changes to READY. Otherwise, it will only parse and validate the SCXML document, then wait for your call to start().

SCxml.sessions

An Array of all JSSCxml sessions (interpreters) on the page, indexed by their session ID. Because the SID is never lower than 1, SCxml.sessions[0] is always null and the array's length is one larger than the number of sessions ever created.

You should never modify this array, only use it to access sessions.

SCxml.parseSCXMLTags()

finds all <scxml> elements on the page, and creates an SCXML instance for them if they have a src attribute. The instance is anchored to the <scxml> element and will start running automatically (interpretASAP is true).

new SCxml.ExternalEvent(string name, string origin, string origintype, number invokeid, any data)

returns an instance of JSSC's representation for external events, suitable for passing to the fireEvent() method.

The meaning of the arguments is defined in the SCXML recommendation: 5.11.1 The Internal Structure of Events. Only name (the first one) is required.

Methods and properties of SCxml instances

start()

if the instance is ready, starts running it. That's all.

pauseNext(boolean macrostep)

requires SCxmlDebug.js

will pause the interpreter before the next microstep, or macrostep if the argument is true. Note that this method returns before the interpreter is actually paused, unless it was stable.

Delayed events' and setTimeout timers will also be paused, although system time will obviously continue ticking so there may be some side-effects. setInterval will be supported soon.

clean()

Removes the interpreter's anchor (only if it is an <scxml> element) and datamodel <iframe> from the document, and also a bunch of references to facilitate garbage collection. If you call this while the interpreter is running, it will first try to terminate properly.

resume()

requires SCxmlDebug.js

immediately resumes a paused interpreter.

fireEvent(mixed event)
fireEvent(string name, any data)

if the interpreter is running, appends an event to its external queue. If the interpreter was waiting, tries to take transitions with the new event.

event
Required in the one-argument version
an instance of SCxml.Event will be used directly. JSSC also natively supports instances of window.Event (a DOM Event), which are converted into an SCxml.ExternalEvent before being queued. In that case, the DOM event's type property is used for the SCxml.Event's name, and all the DOM event's properties will be available in the SCXML system variable _event.data.
name
Required in the two-arguments version
the new event's name
data
Default: undefined
in the two-arguments version: the new event's data, which can be anything

readyState

is one of:

  1. SCxml.LOADING
  2. SCxml.READY
  3. SCxml.RUNNING
  4. SCxml.FINISHED

dom

references the SCXML Document that the instance is interpreting. At this time, modifications to the Document after the instance is created can have strange consequences.

configuration

An object whose enumarable properties reference each active state by their id. It is not ordered.

Events

These DOM events will be fired at the SCxml instance's anchor when the right conditions are met.

ready

fired when the interpreter has parsed and validated the source, and is ready to start. It will then start immediately if interpretASAP was true.

pause

fired when the interpreter pauses (automatically or after a pauseNext() call).

finished

fires when the interpreter reaches a top-level final state and terminates.

waiting

fires whenever the interpreter becomes stable and has no more events to process.

exit

fires when states are exited during transitions. The event's detail property is a list of the exited states' ids.

enter

fires when states are entered during transitions. The event's detail property is a list of the entered states' ids.

queue

fires whenever an event is added to one of the queues (for whatever reason, like an error.execution, a <raise> element or your own call to fireEvent()). The detail property references the new event.

consume

fires whenever an event is consumed from one of the queues. The detail property contains the string "internal" or "external", depending on the queue the event was taken from.