Client scripting with ECMAScript

Summary: This page documents the extended ECMAScript environment of the Gradient client.

The SVG DOM of Squiggle has a lot in common with the DOM of any normal standards-compliant browser such as Firefox, in that you have basic commands such as alert and confirm, and objects that let you do a variety of things in the environment. However, some additions have been made to the environment to allow basic interaction with XMPP, and apply your own directives to the document.

Important: at present, single-line comments don't work due to a parsing bug. What this means is that you should use /* multi-line comments */ for all comments until this bug is fixed.

Extensions to the script environment are all functions that can be called anywhere in the script, just like alert. In addition to these extensions, you can trap XMPP events within the DOM by declaring certain functions.

The functions can be broken down into two categories; XMPP functions and directives, with one general-purpose function:

log

The first custom function is alert's silent partner, log. log() prints all the arguments you give it to the log file of the canvas it was called in.

Syntax: log(arg1, arg2, ...)

Return value: none.

XMPP extensions

The XMPP extensions allow a limited degree of interaction between an XML document and an XMPP network. The capabilities have been deliberately limited with the following goals in mind:

If you find a way of doing one of these things from within ECMAScript, then I would consider this to be a security vulnerability - please let me know and I'll fix it.

sendMessage

This command sends a message stanza over the XMPP network. The client must have a subscription to the target JID, if different from the controller JID (the JID from which the document was loaded).

If the message is sent to the controller JID, then the thread element is specified by the canvas before the stanza is sent.

Syntax: sendMessage(elements, [messageType[, remoteJID]])

elements
Either a single element or an array of elements to send as child elements of the message stanza.
messageType
(optional) the message type. Defaults to "normal". Must be one of "chat", "error", "groupchat", "headline", or "normal". (case insensitive)
remoteJID
(optional) the recipient of the message. Defaults to the JID from which the document was loaded. The client JID must have a subscription to this JID.

Return value: none.

sendIQ

Sends an IQ get or set to the target JID. The client must have a subscription to the target JID, if different from the controller JID.

Syntax: sendGet(element, [iqType[, remoteJID]])

element
A single element.
iqType
The IQ type. Either "get" or "set" (case insensitive). Defaults to "get"
remoteJID
(optional) the recipient of the message. Defaults to the JID from which the document was loaded. The client JID must have a subscription to this JID.

Return value: the element returned by the target entity as specified by the JID.

Directive extensions

The directive functions are intended to enable scripts to carry out the same modifications on the document that directives received from the server can do.

The rationale behind this is that it's a bit pointless to have a script send a message or IQ to the server to request modification of the document when the script already knows what needs to be done.

setNSPrefix

When sending directives from the server, each directive can specify its own namespace context. Within ECMAScript that would be ugly, so instead we have a shortcut: one namespace context is used across many directives.

The namespace context is persistent across the lifetime of the document, is used for all ECMAScript-executed directives.

Syntax: setNSPrefix(prefix, uri)

prefix
The namespace prefix for use in future directive XPath expressions.
uri
The URI for this prefix.

Return value: none.

appendTo

As with the appendto directive attribute, this function appends the given element(s) to all elements matching the given XPath expression.

Syntax: appendTo(elements, expression)

elements
Either one element or an array of elements.
expression
An XPath expression that returns a list of elements.

Return value: none.

insertBefore

As with the insertbefore directive attribute, this function inserts the given element(s) before all elements matching the given XPath expression.

Syntax: insertBefore(elements, expression)

elements
Either one element or an array of elements.
expression
An XPath expression that returns a list of elements.

Return value: none.

replace

As with the replace directive attribute, this function replaces all elements matching the given XPath expression with the provided element.

Syntax: insertBefore(element, expression)

element
An element.
expression
An XPath expression that returns a list of elements.

Return value: none.

remove

As with the remove directive attribute, this function removes all elements matching the given XPath expression.

Syntax: remove(expression)

expression
An XPath expression that returns a list of elements.

Return value: none.

Summary

These are the functions currently available from within the ECMAScript environment of the Gradient client. In addition to these extensions, you can trap XMPP events within the DOM by declaring certain functions. Further extensions are planned, see the planning and todo list pages.

© 2006. Some rights reserved. Author: Ian Sollars.