2 <API id='Sablotron Extensions API'>
5 &copy; 2001-2002 Ginger Alliance<BR/>
6 <I>revision 02-08-05</I><BR/>
11 <ENTRY id='.Introduction'>
12 <TYPE value='.General'/>
14 This reference guide describes the DOM API for Sablotron Extension
15 functions in JavaScript. Sablotron supports an extension element
16 funct:script element (where funct prefix is bound to the
17 'http://exslt.org/functions' namespace URI) with
18 language="func:ecmascript" or language="func:javascript" (just
19 "ecmascript" or "javascript" work as well).
22 The API implementation follows the ECMAScript/DOM2 Language Binding
23 defined in <S>DOM Level2</S>, Appendix E.<P/>
25 However, there are few exceptions from the specifications:<P/>
27 <B>*</B> The DOM model is read only<BR/>
28 <B>*</B> DOM functions handling namespaces (with NS in their name) are
29 not supported (throw NOT_SUPPORTED exception).<BR/>
30 <B>*</B> XSLTContext.stringValue method is not supported.<BR/>
31 <B>*</B> Document.getElementsByTagName{NS} methods aren't supported.<BR/>
32 <B>*</B> Element.getElementsByTagName{NS} methods aren't supported.<BR/>
33 <B>*</B> DTD definition nodes are not supported.<P/>
35 As the model is read-only and because of distinctions in the DOM
36 and the XPath models, some objects can't be ever instantiated.
37 Those objects (DocumentFragment, Text, Comment, CDATASection,
38 DocumentType, Notation, Entity, EntityReference, ProcessingInstruction)
39 are not supported.<P/>
41 See <C>.Objects</C> for the list of implemented objects.<P/>
43 Type <C>.Conversions</C> and <C>XSLTContext</C> object binding are
44 implemented according to <S>XSLT 1.1</S>, Appendix C3.
47 <EXTERNALREF name="DOM Level2" value="http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/"/>
48 <EXTERNALREF name="XSLT 1.1" value="http://www.w3.org/TR/xslt11/"/>
52 <TYPE value='.General'/>
54 A global object <C>XSLTContext</C> provides an access to XSLT
55 and XPath expession context.
57 The following DOM objects are available:<BR/>
58 <C>DOMException</C><BR/>
59 <C>DOMImplementation</C><BR/>
63 <C>NamedNodeMap</C><BR/>
64 <C>CharacterData</C><BR/>
70 <ENTRY id='.Conversions'>
71 <TYPE value='.General'/>
73 The following function argument conversions are performed:<P/>
74 <B>*</B> An XPath string object is mapped to an ECMAScript string
76 <B>*</B> An XPath number object is mapped to an ECMAScript number
78 <B>*</B> An XPath boolean object is mapped to an ECMAScript boolean
80 <B>*</B> An XPath node-set object is mapped to the ECMAScript binding
81 for the DOM <C>NodeList</C>.<BR/>
82 <B>*</B> An XSLT external object is mapped to the ECMAScript object that
85 The following conversions are performed on return values:<P/>
86 <B>*</B> An ECMAScript string value or String object is mapped to an
87 XPath string object.<BR/>
88 <B>*</B> An ECMAScript number value or Number object is mapped to an
89 XPath number object.<BR/>
90 <B>*</B> An ECMAScript boolean value or Boolean object is mapped to an
91 XPath boolean object.<BR/>
92 <B>*</B> An ECMAScript object that is an instance of either
93 <C>Document</C>, <C>Node</C>, <C>NodeList</C>, <C>Attr</C>,
94 <C>Element</C> or <C>CharacterData</C> are mapped to an XPath
96 <B>*</B> The ECMAScript null value is mapped to an XSLT external
98 <B>*</B> The ECMAScript undefined value is mapped to an empty
100 <B>*</B> Any other ECMAScript object is mapped to an XSLT external
106 <ENTRY id='.Example'>
107 <TYPE value='.General'/>
109 An example how to use the DOM in JavaScript extension functions. The
110 function returns a sum of all attributes in a nodeset.
115 &lt;?xml version="1.0"?&gt;
116 &lt;xsl:stylesheet version="1.0"
117 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
118 xmlns:func="http://www.exslt.org/functions"
119 xmlns:my="http://gingerall.org/sablot/myfunc"
120 extension-element-prefixes="func"
121 exclude-result-prefixes="my"&gt;
123 &lt;xsl:output method="xml" indent="yes"/&gt;
125 &lt;func:script implements-prefix="my" language="javascript"&gt;&lt;![CDATA[
127 function attrSum(nodeset) {
129 for (i = 0; i &lt; nodeset.length; i++) {
130 for (j = 0; j &lt; nodeset[i].attributes.length; j++) {
131 sum += Number(nodeset[i].attributes.item(j));
138 &lt;xsl:fallback&gt;
139 &lt;xsl:text&gt;JS extension no supported!&lt;/xsl:text&gt;
140 &lt;/xsl:fallback&gt;
141 &lt;/func:script&gt;
144 &lt;xsl:template match="/root"&gt;
146 &lt;xsl:choose&gt;
147 &lt;xsl:when test="function-available('my:attrSum')"&gt;
148 &lt;xsl:text&gt;The sum of attributes: &lt;/xsl:text&gt;
149 &lt;xsl:value-of select="my:attrSum(node)"/&gt;
150 &lt;/xsl:when&gt;
151 &lt;xsl:otherwise&gt;Function not available!&lt;/xsl:otherwise&gt;
152 &lt;/xsl:choose&gt;
153 &lt;/root&gt;
154 &lt;/xsl:template&gt;
157 &lt;/xsl:stylesheet&gt;
161 &lt;?xml version="1.0"?&gt;
164 &lt;node a="1" b="2"/&gt;
165 &lt;node c="10"/&gt;
166 &lt;node a="5" b="6" c="7"/&gt;
168 &lt;/root&gt;
172 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
173 &lt;root&gt;The sum of attributes: 31&lt;/root&gt;
178 <ENTRY id='.Debugging'>
179 <TYPE value='.General'/>
181 To facilitate the debugging of JS scripts it's possible to
182 write to Sablotron's log file from a script.
186 <PARAM name="string" type="String">
191 This function writes a string to Sablotron's log file. The log file
192 must be specified either from the command line
193 <C>sabcmd -L logfile ...</C> or with the <C>SablotSetLog</C>
200 <ENTRY id='XSLTContext'>
201 <TYPE value='Objects'/>
203 The XSLTContext global object has the following properties:<BR/>
204 <C>XSLTContext.contextNode</C><BR/>
205 <C>XSLTContext.contextPosition</C><BR/>
206 <C>XSLTContext.contextSize</C><BR/>
207 <C>XSLTContext.currentNode</C><BR/>
208 <C>XSLTContext.ownerDocument</C><BR/>
212 <ENTRY id='DOMException'>
213 <TYPE value='Objects'/>
215 The DOMException object has the following properties:<BR/>
216 <C>DOMException.code</C><P/>
218 The DOMException class has the following constants:<P/>
219 DOMException.INDEX_SIZE_ERR, type Number, value 1.<BR/>
220 DOMException.DOMSTRING_SIZE_ERR, type Number, value 2.<BR/>
221 DOMException.HIERARCHY_REQUEST_ERR, type Number, value 3.<BR/>
222 DOMException.WRONG_DOCUMENT_ERR, type Number, value 4.<BR/>
223 DOMException.INVALID_CHARACTER_ERR, type Number, value 5.<BR/>
224 DOMException.NO_DATA_ALLOWED_ERR, type Number, value 6.<BR/>
225 DOMException.NO_MODIFICATION_ALLOWED_ERR, type Number, value 7.<BR/>
226 DOMException.NOT_FOUND_ERR, type Number, value 8.<BR/>
227 DOMException.NOT_SUPPORTED_ERR, type Number, value 9.<BR/>
228 DOMException.INUSE_ATTRIBUTE_ERR, type Number, value 10.<BR/>
229 DOMException.INVALID_STATE_ERR, type Number, value 11.<BR/>
230 DOMException.SYNTAX_ERR, type Number, value 12.<BR/>
231 DOMException.INVALID_MODIFICATION_ERR, type Number, value 13.<BR/>
232 DOMException.NAMESPACE_ERR, type Number, value 14.<BR/>
233 DOMException.INVALID_ACCESS_ERR, type Number, value 15.<BR/>
237 <ENTRY id='DOMImplementation'>
238 <TYPE value='Objects'/>
240 The DOMImplementation object has the following methods:<BR/>
241 <C>DOMImplementation.hasFeature()</C><BR/>
245 <ENTRY id='Document'>
246 <TYPE value='Objects'/>
248 Document has the all the properties and methods of the <C>Node</C>
249 object as well as the properties and methods defined below.<P/>
251 The Document object has the following properties:<BR/>
252 <C>Document.implementation</C><BR/>
253 <C>Document.documentElement</C><BR/>
258 <TYPE value='Objects'/>
260 The Node object has the following properties:<BR/>
261 <C>Node.nodeName</C><BR/>
262 <C>Node.nodeValue</C><BR/>
263 <C>Node.nodeType</C><BR/>
264 <C>Node.parentNode</C><BR/>
265 <C>Node.childNodes</C><BR/>
266 <C>Node.firstChild</C><BR/>
267 <C>Node.lastChild</C><BR/>
268 <C>Node.previousSibling</C><BR/>
269 <C>Node.nextSibling</C><BR/>
270 <C>Node.attributes</C><BR/>
271 <C>Node.ownerDocument</C><BR/>
272 <C>Node.namespaceURI</C><BR/>
273 <C>Node.prefix</C><BR/>
274 <C>Node.localName</C><BR/>
277 The Node object has the following methods:<BR/>
278 <C>Node.hasChildNodes()</C><BR/>
279 <C>Node.isSupported()</C><BR/>
280 <C>Node.hasAttributes()</C><BR/>
283 The Node class has the following constants:<P/>
284 Node.ELEMENT_NODE, type Number, value 1.<BR/>
285 Node.ATTRIBUTE_NODE, type Number, value 2.<BR/>
286 Node.TEXT_NODE, type Number, value 3.<BR/>
287 Node.CDATA_SECTION_NODE, type Number, value 4.<BR/>
288 Node.ENTITY_REFERENCE_NODE, type Number, value 5.<BR/>
289 Node.ENTITY_NODE, type Number, value 6.<BR/>
290 Node.PROCESSING_INSTRUCTION_NODE, type Number, value 7.<BR/>
291 Node.COMMENT_NODE, type Number, value 8.<BR/>
292 Node.DOCUMENT_NODE, type Number, value 9.<BR/>
293 Node.DOCUMENT_TYPE_NODE, type Number, value 10.<BR/>
294 Node.DOCUMENT_FRAGMENT_NODE, type Number, value 11.<BR/>
295 Node.NOTATION_NODE, type Number, value 12.<BR/>
299 <ENTRY id='NodeList'>
300 <TYPE value='Objects'/>
302 The NodeList object has the following properties:<BR/>
303 <C>NodeList.length</C><BR/>
306 The NodeList object has the following methods:<BR/>
307 <C>NodeList.item()</C><BR/>
312 <ENTRY id='NamedNodeMap'>
313 <TYPE value='Objects'/>
315 The NamedNodeMap object has the following properties:<BR/>
316 <C>NamedNodeMap.length</C><BR/>
319 The NamedNodeMap object has the following methods:<BR/>
320 <C>NamedNodeMap.getNamedItem()</C><BR/>
321 <C>NamedNodeMap.item()</C><BR/>
326 <ENTRY id='CharacterData'>
327 <TYPE value='Objects'/>
329 CharacterData has the all the properties and methods of the <C>Node</C>
330 object as well as the properties and methods defined below.<P/>
332 The CharacterData object has the following properties:<BR/>
333 <C>CharacterData.data</C><BR/>
334 <C>CharacterData.length</C><BR/>
337 The CharacterData object has the following methods:<BR/>
338 <C>CharacterData.substringData()</C><BR/>
344 <TYPE value='Objects'/>
346 Attr has the all the properties and methods of the <C>Node</C> object
347 as well as the properties and methods defined below.<P/>
349 The Attr object has the following properties:<BR/>
350 <C>Attr.name</C><BR/>
351 <C>Attr.specified</C><BR/>
352 <C>Attr.value</C><BR/>
353 <C>Attr.ownerElement</C><BR/>
359 <TYPE value='Objects'/>
361 Element has the all the properties and methods of the <C>Node</C>
362 object as well as the properties and methods defined below.<P/>
364 The Element object has the following properties:<BR/>
365 <C>Element.tagName</C><BR/>
368 The Element object has the following methods:<BR/>
369 <C>Element.getAttribute()</C><BR/>
370 <C>Element.getAttributeNode()</C><BR/>
371 <C>Element.hasAttribute()</C><BR/>
376 <!-- DOMException Object -->
378 <ENTRY id="DOMException.code">
379 <TYPE value="DOMException"/>
382 <PARAM name="(PROP)" type="Number">
383 This property is of type Number.
387 This function always returns FALSE currently.
391 <!-- DOMImplementation Object -->
393 <ENTRY id="DOMImplementation.hasFeature()">
394 <TYPE value="DOMImplementation"/>
396 hasFeature(feature, version)
397 <PARAM name="feature" type="String">
398 The feature parameter is of type String.
400 <PARAM name="version" type="String">
401 The version parameter is of type String.
403 <PARAM name="(RET)" type="Boolean">
404 This method returns a Boolean.
408 This function always returns FALSE currently.
412 <!-- Document Object -->
414 <ENTRY id="Document.implementation">
415 <TYPE value="Document"/>
418 <PARAM name="(PROP)" type="DOMImplementation">
419 This read-only property is a DocumentType object.
424 <ENTRY id="Document.documentElement">
425 <TYPE value="Document"/>
428 <PARAM name="(PROP)" type="Element">
429 This read-only property is an Element object.
436 <ENTRY id="Node.nodeName">
440 <PARAM name="(PROP)" type="String">
441 This read-only property is of type String.
446 <ENTRY id="Node.nodeValue">
450 <PARAM name="(PROP)" type="String">
451 This property is of type String.
455 This property can raise a <C>DOMException</C> object on setting and can
456 raise a <C>DOMException</C> object on retrieval.
460 <ENTRY id="Node.nodeType">
464 <PARAM name="(PROP)" type="Number">
465 This read-only property is of type Number.
469 See <C>Node</C> class constants.
473 <ENTRY id="Node.parentNode">
477 <PARAM name="(PROP)" type="Node">
478 This read-only property is a Node object.
483 <ENTRY id="Node.childNodes">
487 <PARAM name="(PROP)" type="NodeList">
488 This read-only property is a NodeList object.
493 <ENTRY id="Node.firstChild">
497 <PARAM name="(PROP)" type="Node">
498 This read-only property is a Node object.
503 <ENTRY id="Node.lastChild">
507 <PARAM name="(PROP)" type="Node">
508 This read-only property is a Node object.
513 <ENTRY id="Node.previousSibling">
517 <PARAM name="(PROP)" type="Node">
518 This read-only property is a Node object.
523 <ENTRY id="Node.nextSibling">
527 <PARAM name="(PROP)" type="Node">
528 This read-only property is a Node object.
533 <ENTRY id="Node.attributes">
537 <PARAM name="(PROP)" type="NamedNodeMap">
538 This read-only property is a NamedNodeMap object.
543 <ENTRY id="Node.ownerDocument">
547 <PARAM name="(PROP)" type="Document">
548 This read-only property is a Document object.
553 <ENTRY id="Node.namespaceURI">
557 <PARAM name="(PROP)" type="String">
558 This read-only property is of type String.
563 <ENTRY id="Node.prefix">
567 <PARAM name="(PROP)" type="String">
568 This property is of type String.
572 This property can raise a <C>DOMException</C> object on setting.
576 <ENTRY id="Node.localName">
580 <PARAM name="(PROP)" type="String">
581 This read-only property is of type String.
586 <ENTRY id="Node.hasAttributes()">
590 <PARAM name="(RET)" type="Boolean">
591 This method returns a Boolean.
596 <ENTRY id="Node.hasChildNodes()">
600 <PARAM name="(RET)" type="Boolean">
601 This method returns a Boolean.
606 <ENTRY id="Node.isSupported()">
609 isSupported(feature, version)
610 <PARAM name="feature" type="String">
611 The feature parameter is of type String.
613 <PARAM name="version" type="String">
614 The version parameter is of type String.
616 <PARAM name="(RET)" type="Boolean">
617 This method returns a Boolean.
621 This function always returns FALSE currently.
625 <!-- NodeList Object -->
627 <ENTRY id="NodeList.length">
628 <TYPE value="NodeList"/>
631 <PARAM name="(PROP)" type="Number">
632 This read-only property is of type Number.
637 <ENTRY id="NodeList.item()">
638 <TYPE value="NodeList"/>
641 <PARAM name="index" type="Number">
642 The index parameter is of type Number.
644 <PARAM name="(RET)" type="Node">
645 This method returns a Node object.
649 This object can also be dereferenced using square bracket notation
650 (e.g. obj[1]). Dereferencing with an integer index is equivalent to
651 invoking the item method with that index.
654 The very first item has index 0.
658 <!-- NamedNodeMap Object -->
660 <ENTRY id="NamedNodeMap.length">
661 <TYPE value="NamedNodeMap"/>
664 <PARAM name="(PROP)" type="Number">
665 This read-only property is of type Number.
670 <ENTRY id="NamedNodeMap.item()">
671 <TYPE value="NamedNodeMap"/>
674 <PARAM name="index" type="Number">
675 The index parameter is of type Number.
677 <PARAM name="(RET)" type="Node">
678 This method returns a Node object.
682 The very first item has index 0.
686 <ENTRY id="NamedNodeMap.getNamedItem()">
687 <TYPE value="NamedNodeMap"/>
690 <PARAM name="name" type="String">
691 The name parameter is of type String.
693 <PARAM name="(RET)" type="Node">
694 This method returns a Node object.
699 <!-- CharacterData Object -->
701 <ENTRY id="CharacterData.data">
702 <TYPE value="CharacterData"/>
705 <PARAM name="(PROP)" type="String">
706 This property is of type String.
710 This property can raise a <C>DOMException</C> object on setting and can
711 raise a <C>DOMException</C> object on retrieval.length
715 <ENTRY id="CharacterData.length">
716 <TYPE value="CharacterData"/>
719 <PARAM name="(PROP)" type="Number">
720 This read-only property is of type Number.
725 <ENTRY id="CharacterData.substringData()">
726 <TYPE value="CharacterData"/>
728 substringData(offset, count)
729 <PARAM name="offset" type="Number">
730 The offset parameter is of type Number.
732 <PARAM name="count" type="Number">
733 The count parameter is of type Number.
735 <PARAM name="(RET)" type="Node">
736 This method returns a String.
740 This method can raise a <C>DOMException</C> object.
743 The very first item has index 0.
749 <ENTRY id="Attr.name">
753 <PARAM name="(PROP)" type="String">
754 This read-only property is of type String.
759 <ENTRY id="Attr.specified">
763 <PARAM name="(PROP)" type="Boolean">
764 This read-only property is of type Boolean.
769 <ENTRY id="Attr.value">
773 <PARAM name="(PROP)" type="String">
774 This property is of type String.
778 This property can raise a <C>DOMException</C> object on setting.
782 <ENTRY id="Attr.ownerElement">
786 <PARAM name="(PROP)" type="Element">
787 This read-only property is a Element object.
792 <!-- Element Object -->
794 <ENTRY id="Element.tagName">
795 <TYPE value="Element"/>
798 <PARAM name="(PROP)" type="String">
799 This read-only property is of type String.
804 <ENTRY id="Element.getAttribute()">
805 <TYPE value="Element"/>
808 <PARAM name="name" type="String">
809 The name parameter is of type String.
811 <PARAM name="(RET)" type="String">
812 This method returns a String.
817 <ENTRY id="Element.getAttributeNode()">
818 <TYPE value="Element"/>
820 getAttributeNode(name)
821 <PARAM name="name" type="String">
822 The name parameter is of type String.
824 <PARAM name="(RET)" type="Attr">
825 This method returns a Attr object.
830 <ENTRY id="Element.hasAttribute()">
831 <TYPE value="Element"/>
834 <PARAM name="name" type="String">
835 The name parameter is of type String.
837 <PARAM name="(RET)" type="Boolean">
838 This method returns a Boolean.
843 <!-- XSLTContext Object -->
845 <ENTRY id="XSLTContext.contextNode">
846 <TYPE value="XSLTContext"/>
849 <PARAM name="(PROP)" type="Node">
850 Context node from XPath expression context.
855 <ENTRY id="XSLTContext.contextPosition">
856 <TYPE value="XSLTContext"/>
859 <PARAM name="(PROP)" type="Number">
860 Context position from XPath expression context.
865 <ENTRY id="XSLTContext.contextSize">
866 <TYPE value="XSLTContext"/>
869 <PARAM name="(PROP)" type="Number">
870 Context size from XPath expression context.
875 <ENTRY id="XSLTContext.currentNode">
876 <TYPE value="XSLTContext"/>
879 <PARAM name="(PROP)" type="Node">
880 Current node from XSLT context.
885 <ENTRY id="XSLTContext.ownerDocument">
886 <TYPE value="XSLTContext"/>
889 <PARAM name="(PROP)" type="Document">
890 Document to be used for creating nodes.