# Sablotron Extensions API Reference

Conversions | .General

#### Description

The following function argument conversions are performed:

* An XPath string object is mapped to an ECMAScript string value.
* An XPath number object is mapped to an ECMAScript number value.
* An XPath boolean object is mapped to an ECMAScript boolean value.
* An XPath node-set object is mapped to the ECMAScript binding for the DOM `NodeList`.
* An XSLT external object is mapped to the ECMAScript object that it wraps.

The following conversions are performed on return values:

* An ECMAScript string value or String object is mapped to an XPath string object.
* An ECMAScript number value or Number object is mapped to an XPath number object.
* An ECMAScript boolean value or Boolean object is mapped to an XPath boolean object.
* An ECMAScript object that is an instance of either `Document`, `Node`, `NodeList`, `Attr`, `Element` or `CharacterData` are mapped to an XPath node-set.
* The ECMAScript null value is mapped to an XSLT external object.
* The ECMAScript undefined value is mapped to an empty node-set.
* Any other ECMAScript object is mapped to an XSLT external object

#### See Also

Groups | [ .General ]
Entries | [ Attr | CharacterData | Document | Element | Node | NodeList ]

Debugging | .General

#### Summary

To facilitate the debugging of JS scripts it's possible to write to Sablotron's log file from a script.

#### Syntax

           log(string)

Name | Type | Description
--- | --- | ---
`string` | `String` | String value.

#### Description

This function writes a string to Sablotron's log file. The log file must be specified either from the command line `sabcmd -L logfile ...` or with the `SablotSetLog` API function.

#### See Also

Groups | [ .General ]

Example | .General

#### Summary

An example how to use the DOM in JavaScript extension functions. The function returns a sum of all attributes in a nodeset.

#### Example

    Template:
    --------------------
    <?xml version="1.0"?>
    <xsl:stylesheet version="1.0"
       xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
       xmlns:func="http://www.exslt.org/functions"
       xmlns:my="http://gingerall.org/sablot/myfunc"
       extension-element-prefixes="func"
       exclude-result-prefixes="my">

       <xsl:output method="xml" indent="yes"/>

       <func:script implements-prefix="my" language="javascript"><![CDATA[

       function attrSum(nodeset) {
         var sum = 0;
         for (i = 0; i < nodeset.length; i++) {
           for (j = 0; j < nodeset[i].attributes.length; j++) {
             sum += Number(nodeset[i].attributes.item(j));
           }
         }
         return sum;
       }

       ]]>
       <xsl:fallback>
         <xsl:text>JS extension no supported!</xsl:text>
       </xsl:fallback>
       </func:script>

       <xsl:template match="/root">
         <root>
           <xsl:choose>
             <xsl:when test="function-available('my:attrSum')">
               <xsl:text>The sum of attributes: </xsl:text>
               <xsl:value-of select="my:attrSum(node)"/>
             </xsl:when>
             <xsl:otherwise>Function not available!</xsl:otherwise>
           </xsl:choose>
         </root>
       </xsl:template>

    </xsl:stylesheet>

    Data:
    --------------------
    <?xml version="1.0"?>
    <root>

       <node a="1" b="2"/>
       <node c="10"/>
       <node a="5" b="6" c="7"/>

    </root>

    Result:
    --------------------
    <?xml version="1.0" encoding="UTF-8"?>
    <root>The sum of attributes: 31</root>

#### See Also

Groups | [ .General ]

Introduction | .General

#### Summary

This reference guide describes the DOM API for Sablotron Extension functions in JavaScript. Sablotron supports an extension element funct:script element (where funct prefix is bound to the 'http://exslt.org/functions' namespace URI) with language="func:ecmascript" or language="func:javascript" (just "ecmascript" or "javascript" work as well).

#### Description

The API implementation follows the ECMAScript/DOM2 Language Binding defined in DOM Level2, Appendix E.

However, there are few exceptions from the specifications:

* The DOM model is read only
* DOM functions handling namespaces (with NS in their name) are not supported (throw NOT_SUPPORTED exception).
* XSLTContext.stringValue method is not supported.
* Document.getElementsByTagName{NS} methods aren't supported.
* Element.getElementsByTagName{NS} methods aren't supported.
* DTD definition nodes are not supported.

As the model is read-only and because of distinctions in the DOM and the XPath models, some objects can't be ever instantiated. Those objects (DocumentFragment, Text, Comment, CDATASection, DocumentType, Notation, Entity, EntityReference, ProcessingInstruction) are not supported.

See `.Objects` for the list of implemented objects.

Type `.Conversions` and `XSLTContext` object binding are implemented according to XSLT 1.1, Appendix C3.

#### See Also

Groups | [ .General ]
Documents | [ DOM Level2 | XSLT 1.1 ]
Entries | [ .Conversions | .Objects | XSLTContext ]

Objects | .General

#### Description

A global object `XSLTContext` provides an access to XSLT and XPath expession context.

The following DOM objects are available:
`DOMException`
`DOMImplementation`
`Document`
`Node`
`NodeList`
`NamedNodeMap`
`CharacterData`
`Attr`
`Element`

#### See Also

Groups | [ .General ]
Entries | [ Attr | CharacterData | DOMException | DOMImplementation | Document | Element | NamedNodeMap | Node | NodeList | XSLTContext ]

Attr | Objects

#### Description

Attr has the all the properties and methods of the `Node` object as well as the properties and methods defined below.

The Attr object has the following properties:
`Attr.name`
`Attr.specified`
`Attr.value`
`Attr.ownerElement`

#### See Also

Groups | [ Objects ]
Entries | [ Attr.name | Attr.ownerElement | Attr.specified | Attr.value | Node ]

Attr.name | Attr

#### Syntax

           name

Name | Type | Description
--- | --- | ---
`(PROP)` | `String` | This read-only property is of type String.

#### See Also

Groups | [ Attr ]

Attr.ownerElement | Attr

#### Syntax

           ownerElement

Name | Type | Description
--- | --- | ---
`(PROP)` | `Element` | This read-only property is a Element object.

#### See Also

Groups | [ Attr ]
Entries | [ Element ]

Attr.specified | Attr

#### Syntax

           specified

Name | Type | Description
--- | --- | ---
`(PROP)` | `Boolean` | This read-only property is of type Boolean.

#### See Also

Groups | [ Attr ]

Attr.value | Attr

#### Syntax

           value

Name | Type | Description
--- | --- | ---
`(PROP)` | `String` | This property is of type String.

#### Notes

This property can raise a `DOMException` object on setting.

#### See Also

Groups | [ Attr ]
Entries | [ DOMException ]

CharacterData | Objects

#### Description

CharacterData has the all the properties and methods of the `Node` object as well as the properties and methods defined below.

The CharacterData object has the following properties:
`CharacterData.data`
`CharacterData.length`

The CharacterData object has the following methods:
`CharacterData.substringData()`

#### See Also

Groups | [ Objects ]
Entries | [ CharacterData.data | CharacterData.length | CharacterData.substringData() | Node ]

CharacterData.data | CharacterData

#### Syntax

           data

Name | Type | Description
--- | --- | ---
`(PROP)` | `String` | This property is of type String.

#### Notes

This property can raise a `DOMException` object on setting and can raise a `DOMException` object on retrieval.length

#### See Also

Groups | [ CharacterData ]
Entries | [ DOMException ]

CharacterData.length | CharacterData

#### Syntax

           length

Name | Type | Description
--- | --- | ---
`(PROP)` | `Number` | This read-only property is of type Number.

#### See Also

Groups | [ CharacterData ]

CharacterData.substringData() | CharacterData

#### Syntax

           substringData(offset, count)

Name | Type | Description
--- | --- | ---
`offset` | `Number` | The offset parameter is of type Number.
`count` | `Number` | The count parameter is of type Number.
`(RET)` | `Node` | This method returns a String.

#### Notes

This method can raise a `DOMException` object. The very first item has index 0.

#### See Also

Groups | [ CharacterData ]
Entries | [ DOMException | Node ]

DOMException | Objects

#### Description

The DOMException object has the following properties:
`DOMException.code`

The DOMException class has the following constants:

DOMException.INDEX_SIZE_ERR, type Number, value 1.
DOMException.DOMSTRING_SIZE_ERR, type Number, value 2.
DOMException.HIERARCHY_REQUEST_ERR, type Number, value 3.
DOMException.WRONG_DOCUMENT_ERR, type Number, value 4.
DOMException.INVALID_CHARACTER_ERR, type Number, value 5.
DOMException.NO_DATA_ALLOWED_ERR, type Number, value 6.
DOMException.NO_MODIFICATION_ALLOWED_ERR, type Number, value 7.
DOMException.NOT_FOUND_ERR, type Number, value 8.
DOMException.NOT_SUPPORTED_ERR, type Number, value 9.
DOMException.INUSE_ATTRIBUTE_ERR, type Number, value 10.
DOMException.INVALID_STATE_ERR, type Number, value 11.
DOMException.SYNTAX_ERR, type Number, value 12.
DOMException.INVALID_MODIFICATION_ERR, type Number, value 13.
DOMException.NAMESPACE_ERR, type Number, value 14.
DOMException.INVALID_ACCESS_ERR, type Number, value 15.

#### See Also

Groups | [ Objects ]
Entries | [ DOMException.code ]

DOMException.code | DOMException

#### Syntax

           code

Name | Type | Description
--- | --- | ---
`(PROP)` | `Number` | This property is of type Number.

#### Notes

This function always returns FALSE currently.

#### See Also

Groups | [ DOMException ]

DOMImplementation | Objects

#### Description

The DOMImplementation object has the following methods:
`DOMImplementation.hasFeature()`

#### See Also

Groups | [ Objects ]
Entries | [ DOMImplementation.hasFeature() ]

DOMImplementation.hasFeature() | DOMImplementation

#### Syntax

           hasFeature(feature, version)

Name | Type | Description
--- | --- | ---
`feature` | `String` | The feature parameter is of type String.
`version` | `String` | The version parameter is of type String.
`(RET)` | `Boolean` | This method returns a Boolean.

#### Description

This function always returns FALSE currently.

#### See Also

Groups | [ DOMImplementation ]

Document | Objects

#### Description

Document has the all the properties and methods of the `Node` object as well as the properties and methods defined below.

The Document object has the following properties:
`Document.implementation`
`Document.documentElement`

#### See Also

Groups | [ Objects ]
Entries | [ Document.documentElement | Document.implementation | Node ]

Document.documentElement | Document

#### Syntax

           documentElement

Name | Type | Description
--- | --- | ---
`(PROP)` | `Element` | This read-only property is an Element object.

#### See Also

Groups | [ Document ]
Entries | [ Element ]

Document.implementation | Document

#### Syntax

           implementation

Name | Type | Description
--- | --- | ---
`(PROP)` | `DOMImplementation` | This read-only property is a DocumentType object.

#### See Also

Groups | [ Document ]
Entries | [ DOMImplementation ]

Element | Objects

#### Description

Element has the all the properties and methods of the `Node` object as well as the properties and methods defined below.

The Element object has the following properties:
`Element.tagName`

The Element object has the following methods:
`Element.getAttribute()`
`Element.getAttributeNode()`
`Element.hasAttribute()`

#### See Also

Groups | [ Objects ]
Entries | [ Element.getAttribute() | Element.getAttributeNode() | Element.hasAttribute() | Element.tagName | Node ]

Element.getAttribute() | Element

#### Syntax

           getAttribute(name)

Name | Type | Description
--- | --- | ---
`name` | `String` | The name parameter is of type String.
`(RET)` | `String` | This method returns a String.

#### See Also

Groups | [ Element ]

Element.getAttributeNode() | Element

#### Syntax

           getAttributeNode(name)

Name | Type | Description
--- | --- | ---
`name` | `String` | The name parameter is of type String.
`(RET)` | `Attr` | This method returns a Attr object.

#### See Also

Groups | [ Element ]
Entries | [ Attr ]

Element.hasAttribute() | Element

#### Syntax

           hasAttribute(name)

Name | Type | Description
--- | --- | ---
`name` | `String` | The name parameter is of type String.
`(RET)` | `Boolean` | This method returns a Boolean.

#### See Also

Groups | [ Element ]

Element.tagName | Element

#### Syntax

           tagName

Name | Type | Description
--- | --- | ---
`(PROP)` | `String` | This read-only property is of type String.

#### See Also

Groups | [ Element ]

NamedNodeMap | Objects

#### Description

The NamedNodeMap object has the following properties:
`NamedNodeMap.length`

The NamedNodeMap object has the following methods:
`NamedNodeMap.getNamedItem()`
`NamedNodeMap.item()`

#### See Also

Groups | [ Objects ]
Entries | [ NamedNodeMap.getNamedItem() | NamedNodeMap.item() | NamedNodeMap.length ]

NamedNodeMap.getNamedItem() | NamedNodeMap

#### Syntax

           getNamedItem(name)

Name | Type | Description
--- | --- | ---
`name` | `String` | The name parameter is of type String.
`(RET)` | `Node` | This method returns a Node object.

#### See Also

Groups | [ NamedNodeMap ]
Entries | [ Node ]

NamedNodeMap.item() | NamedNodeMap

#### Syntax

           item(index)

Name | Type | Description
--- | --- | ---
`index` | `Number` | The index parameter is of type Number.
`(RET)` | `Node` | This method returns a Node object.

#### Notes

The very first item has index 0.

#### See Also

Groups | [ NamedNodeMap ]
Entries | [ Node ]

NamedNodeMap.length | NamedNodeMap

#### Syntax

           length

Name | Type | Description
--- | --- | ---
`(PROP)` | `Number` | This read-only property is of type Number.

#### See Also

Groups | [ NamedNodeMap ]

Node | Objects

#### Description

The Node object has the following properties:
`Node.nodeName`
`Node.nodeValue`
`Node.nodeType`
`Node.parentNode`
`Node.childNodes`
`Node.firstChild`
`Node.lastChild`
`Node.previousSibling`
`Node.nextSibling`
`Node.attributes`
`Node.ownerDocument`
`Node.namespaceURI`
`Node.prefix`
`Node.localName`

The Node object has the following methods:
`Node.hasChildNodes()`
`Node.isSupported()`
`Node.hasAttributes()`

The Node class has the following constants:

Node.ELEMENT_NODE, type Number, value 1.
Node.ATTRIBUTE_NODE, type Number, value 2.
Node.TEXT_NODE, type Number, value 3.
Node.CDATA_SECTION_NODE, type Number, value 4.
Node.ENTITY_REFERENCE_NODE, type Number, value 5.
Node.ENTITY_NODE, type Number, value 6.
Node.PROCESSING_INSTRUCTION_NODE, type Number, value 7.
Node.COMMENT_NODE, type Number, value 8.
Node.DOCUMENT_NODE, type Number, value 9.
Node.DOCUMENT_TYPE_NODE, type Number, value 10.
Node.DOCUMENT_FRAGMENT_NODE, type Number, value 11.
Node.NOTATION_NODE, type Number, value 12.

#### See Also

Groups | [ Objects ]
Entries | [ Node.attributes | Node.childNodes | Node.firstChild | Node.hasAttributes() | Node.hasChildNodes() | Node.isSupported() | Node.lastChild | Node.localName | Node.namespaceURI | Node.nextSibling | Node.nodeName | Node.nodeType | Node.nodeValue | Node.ownerDocument | Node.parentNode | Node.prefix | Node.previousSibling ]

Node.attributes | Node

#### Syntax

           attributes

Name | Type | Description
--- | --- | ---
`(PROP)` | `NamedNodeMap` | This read-only property is a NamedNodeMap object.

#### See Also

Groups | [ Node ]
Entries | [ NamedNodeMap ]

Node.childNodes | Node

#### Syntax

           childNodes

Name | Type | Description
--- | --- | ---
`(PROP)` | `NodeList` | This read-only property is a NodeList object.

#### See Also

Groups | [ Node ]
Entries | [ NodeList ]

Node.firstChild | Node

#### Syntax

           firstChild

Name | Type | Description
--- | --- | ---
`(PROP)` | `Node` | This read-only property is a Node object.

#### See Also

Groups | [ Node ]
Entries | [ Node ]

Node.hasAttributes() | Node

#### Syntax

           hasAttributes()

Name | Type | Description
--- | --- | ---
`(RET)` | `Boolean` | This method returns a Boolean.

#### See Also

Groups | [ Node ]

Node.hasChildNodes() | Node

#### Syntax

           hasChildNodes()

Name | Type | Description
--- | --- | ---
`(RET)` | `Boolean` | This method returns a Boolean.

#### See Also

Groups | [ Node ]

Node.isSupported() | Node

#### Syntax

           isSupported(feature, version)

Name | Type | Description
--- | --- | ---
`feature` | `String` | The feature parameter is of type String.
`version` | `String` | The version parameter is of type String.
`(RET)` | `Boolean` | This method returns a Boolean.

#### Notes

This function always returns FALSE currently.

#### See Also

Groups | [ Node ]

Node.lastChild | Node

#### Syntax

           lastChild

Name | Type | Description
--- | --- | ---
`(PROP)` | `Node` | This read-only property is a Node object.

#### See Also

Groups | [ Node ]
Entries | [ Node ]

Node.localName | Node

#### Syntax

           localName

Name | Type | Description
--- | --- | ---
`(PROP)` | `String` | This read-only property is of type String.

#### See Also

Groups | [ Node ]

Node.namespaceURI | Node

#### Syntax

           namespaceURI

Name | Type | Description
--- | --- | ---
`(PROP)` | `String` | This read-only property is of type String.

#### See Also

Groups | [ Node ]

Node.nextSibling | Node

#### Syntax

           nextSibling

Name | Type | Description
--- | --- | ---
`(PROP)` | `Node` | This read-only property is a Node object.

#### See Also

Groups | [ Node ]
Entries | [ Node ]

Node.nodeName | Node

#### Syntax

           nodeName

Name | Type | Description
--- | --- | ---
`(PROP)` | `String` | This read-only property is of type String.

#### See Also

Groups | [ Node ]

Node.nodeType | Node

#### Syntax

           nodeType

Name | Type | Description
--- | --- | ---
`(PROP)` | `Number` | This read-only property is of type Number.

#### Description

See `Node` class constants.

#### See Also

Groups | [ Node ]
Entries | [ Node ]

Node.nodeValue | Node

#### Syntax

           nodeValue

Name | Type | Description
--- | --- | ---
`(PROP)` | `String` | This property is of type String.

#### Notes

This property can raise a `DOMException` object on setting and can raise a `DOMException` object on retrieval.

#### See Also

Groups | [ Node ]
Entries | [ DOMException ]

Node.ownerDocument | Node

#### Syntax

           ownerDocument

Name | Type | Description
--- | --- | ---
`(PROP)` | `Document` | This read-only property is a Document object.

#### See Also

Groups | [ Node ]
Entries | [ Document ]

Node.parentNode | Node

#### Syntax

           parentNode

Name | Type | Description
--- | --- | ---
`(PROP)` | `Node` | This read-only property is a Node object.

#### See Also

Groups | [ Node ]
Entries | [ Node ]

Node.prefix | Node

#### Syntax

           prefix

Name | Type | Description
--- | --- | ---
`(PROP)` | `String` | This property is of type String.

#### Notes

This property can raise a `DOMException` object on setting.

#### See Also

Groups | [ Node ]
Entries | [ DOMException ]

Node.previousSibling | Node

#### Syntax

           previousSibling

Name | Type | Description
--- | --- | ---
`(PROP)` | `Node` | This read-only property is a Node object.

#### See Also

Groups | [ Node ]
Entries | [ Node ]

NodeList | Objects

#### Description

The NodeList object has the following properties:
`NodeList.length`

The NodeList object has the following methods:
`NodeList.item()`

#### See Also

Groups | [ Objects ]
Entries | [ NodeList.item() | NodeList.length ]

NodeList.item() | NodeList

#### Syntax

           item(index)

Name | Type | Description
--- | --- | ---
`index` | `Number` | The index parameter is of type Number.
`(RET)` | `Node` | This method returns a Node object.

#### Notes

This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item method with that index. The very first item has index 0.

#### See Also

Groups | [ NodeList ]
Entries | [ Node ]

NodeList.length | NodeList

#### Syntax

           length

Name | Type | Description
--- | --- | ---
`(PROP)` | `Number` | This read-only property is of type Number.

#### See Also

Groups | [ NodeList ]

XSLTContext | Objects

#### Description

The XSLTContext global object has the following properties:
`XSLTContext.contextNode`
`XSLTContext.contextPosition`
`XSLTContext.contextSize`
`XSLTContext.currentNode`
`XSLTContext.ownerDocument`

#### See Also

Groups | [ Objects ]
Entries | [ XSLTContext.contextNode | XSLTContext.contextPosition | XSLTContext.contextSize | XSLTContext.currentNode | XSLTContext.ownerDocument ]

XSLTContext.contextNode | XSLTContext

#### Syntax

           contextNode

Name | Type | Description
--- | --- | ---
`(PROP)` | `Node` | Context node from XPath expression context.

#### See Also

Groups | [ XSLTContext ]
Entries | [ Node ]

XSLTContext.contextPosition | XSLTContext

#### Syntax

           contextPosition

Name | Type | Description
--- | --- | ---
`(PROP)` | `Number` | Context position from XPath expression context.

#### See Also

Groups | [ XSLTContext ]

XSLTContext.contextSize | XSLTContext

#### Syntax

           contextSize

Name | Type | Description
--- | --- | ---
`(PROP)` | `Number` | Context size from XPath expression context.

#### See Also

Groups | [ XSLTContext ]

XSLTContext.currentNode | XSLTContext

#### Syntax

           currentNode

Name | Type | Description
--- | --- | ---
`(PROP)` | `Node` | Current node from XSLT context.

#### See Also

Groups | [ XSLTContext ]
Entries | [ Node ]

XSLTContext.ownerDocument | XSLTContext

#### Syntax

           ownerDocument

Name | Type | Description
--- | --- | ---
`(PROP)` | `Document` | Document to be used for creating nodes.

#### See Also

Groups | [ XSLTContext ]
Entries | [ Document ]

© 2001-2002 Ginger Alliance
revision 02-08-05
This page was generated by APIDOC