forked from Touffy/JSSCxml
-
Notifications
You must be signed in to change notification settings - Fork 0
/
api.html
180 lines (131 loc) · 8.26 KB
/
api.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
<html>
<head>
<meta charset="utf-8">
<title>JSSCxml API documentation</title>
<style>
h1{ font-weight: normal; }
article h1{
background-color: #d7fbc1;
}
article{
margin-bottom: 2em;
}
.debug{
color: #a68000;
}
</style>
</head>
<body>
<h1>JSSCxml API</h1>
<nav><ol>
<li><a href="#constructor">Constructor</a></li>
<li><a href="#methods">Methods and properties of SCxml instances</a></li>
<li><a href="#events">Events</a></li>
</ol></nav>
<section id="constructor"><h1>Constructor</h1>
<article>
<h1><code>new <strong>SCxml</strong>(mixed <var>source</var>, Element <var>anchor</var>, Object <var>data</var>, boolean <var>interpretASAP</var>)</code></h1>
<p>returns an interpreter instance, attempts to retrieve and parse the <var>source</var>, attaches to the supplied <var>anchor</var>, and starts running as soon as possible if <var>interpretASAP</var> is <code>true</code>.</p>
<dl>
<dt><var>source</var></dt>
<dd>Required</dd>
<dd>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 <var>source</var> 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 <a href="http://www.w3.org/TR/FileAPI/#file">File</a>, JSSC will try to read it and parse it as SCXML source code.</dd>
<dt><var>anchor</var></dt>
<dd>Default: special</dd>
<dd>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 <code>interpreter</code> property pointing to the interpreter instance.</dd>
<dt><var>data</var></dt>
<dd>Default: null</dd>
<dd>Must be an Object. That Object's properties will be available to JavaScript code within the SC, e.g. in <code>expr</code> attribute values and <code><script></code> content. It is the recommended way to include libraries and share objects with the SC.</dd>
<dt><var>interpretASAP</var></dt>
<dd>Default: false</dd>
<dd>If this is <code>true</code>, 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().</dd>
</dl>
</article>
<article><h1><code>SCxml.<strong>sessions</strong></code></h1>
<p>An Array of all JSSCxml sessions (interpreters) on the page, indexed by their session ID. Because the SID is never lower than 1, <code>SCxml.sessions[0]</code> is always <code>null</code> and the array's length is one larger than the number of sessions ever created.</p>
<p>You should <em>never</em> modify this array, only use it to access sessions.</p>
</article>
<article><h1><code>SCxml.<strong>parseSCXMLTags</strong>()</code></h1>
<p>finds all <code><scxml></code> elements on the page, and creates an SCXML instance for them if they have a <code>src</code> attribute. The instance is anchored to the <code><scxml></code> element and will start running automatically (<var>interpretASAP</var> is <code>true</code>).</p>
</article>
<article><h1>new <code>SCxml.<strong>ExternalEvent</strong>(string <var>name</var>, string <var>origin</var>, string <var>origintype</var>, number <var>invokeid</var>, any <var>data</var>)</code></h1>
<p>returns an instance of JSSC's representation for external events, suitable for passing to the fireEvent() method.</p>
<p>The meaning of the arguments is defined in the SCXML recommendation: <a href="http://www.w3.org/TR/scxml/#InternalStructureofEvents">5.11.1 The Internal Structure of Events</a>. Only <var>name</var> (the first one) is required.</p>
</article>
</section>
<section id="methods"><h1>Methods and properties of SCxml instances</h1>
<article><h1><code>start()</code></h1>
<p>if the instance is ready, starts running it. That's all.</p>
</article>
<article><h1><code>pauseNext(boolean <var>macrostep</var>)</code></h1>
<p class="debug">requires SCxmlDebug.js</p>
<p>will pause the interpreter before the next microstep, or macrostep if the argument is <code>true</code>. Note that this method returns before the interpreter is actually paused, unless it was stable.</p>
<p>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.</p>
</article>
<article><h1><code>clean()</code></h1>
<p>Removes the interpreter's anchor (only if it is an <code><scxml></code> element) and datamodel <code><iframe></code> 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.</p>
</article>
<article><h1><code>resume()</code></h1>
<p class="debug">requires SCxmlDebug.js</p>
<p>immediately resumes a paused interpreter.</p>
</article>
<article><h1><code>fireEvent(mixed event)</code><br>
<code>fireEvent(string name, any data)</code></h1>
<p>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.</p>
<dl>
<dt><var>event</var></dt>
<dd>Required in the one-argument version</dd>
<dd>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 <code>_event.data</code>.</dd>
<dt><var>name</var></dt>
<dd>Required in the two-arguments version</dd>
<dd>the new event's name</dd>
<dt><var>data</var></dt>
<dd>Default: undefined</dd>
<dd>in the two-arguments version: the new event's data, which can be anything</dd>
</dl>
</article>
<article><h1><code>readyState</code></h1>
<p>is one of:</p>
<ol start="0">
<li>SCxml.LOADING</li>
<li>SCxml.READY</li>
<li>SCxml.RUNNING</li>
<li>SCxml.FINISHED</li>
</ol>
</article>
<article><h1><code>dom</code></h1>
<p>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.</p>
</article>
<article><h1><code>configuration</code></h1>
<p>An object whose enumarable properties reference each active state by their id. It is <em>not</em> ordered.</p>
</article>
</section>
<section id="events"><h1>Events</h1>
<p>These DOM events will be fired at the SCxml instance's anchor when the right conditions are met.</p>
<article><h1>ready</h1>
<p>fired when the interpreter has parsed and validated the source, and is ready to start. It will then start immediately if <var>interpretASAP</var> was true.</p>
</article>
<article><h1>pause</h1>
<p>fired when the interpreter pauses (automatically or after a pauseNext() call).</p>
</article>
<article><h1>finished</h1>
<p>fires when the interpreter reaches a top-level final state and terminates.</p>
</article>
<article><h1>waiting</h1>
<p>fires whenever the interpreter becomes stable and has no more events to process.</p>
</article>
<article><h1>exit</h1>
<p>fires when states are exited during transitions. The event's <code>detail</code> property is a list of the exited states' ids.</p>
</article>
<article><h1>enter</h1>
<p>fires when states are entered during transitions. The event's <code>detail</code> property is a list of the entered states' ids.</p>
</article>
<article><h1>queue</h1>
<p>fires whenever an event is added to one of the queues (for whatever reason, like an error.execution, a <code><raise></code> element or your own call to fireEvent()). The <code>detail</code> property references the new event.</p>
</article>
<article><h1>consume</h1>
<p>fires whenever an event is consumed from one of the queues. The <code>detail</code> property contains the string "internal" or "external", depending on the queue the event was taken from.</p>
</article>
</section>
</body>
</html>