Xtras and JavaScript

Starting with Director 10 (MX2004) JavaScript was introduced as an alternative scripting language in Director. Existing scripting Xtras work quite well under JavaScript, once you know the basics

Global Xtra Methods vs. Xtra Instances

Most Xtras require that you create an instance with the function "new", and use the instance variable as the object of all of the xtra's commands. The following syntax will do this under Lingo and JavaScript:

variable = new xtra("xtraname")

With FileIO as an example:

instance = new xtra("fileio");

fPath = instance.displayOpen();

Some Xtras do not require an instance. They have global functions and commands that are available simply by calling the function. FileIO Xtra requires an instance but also has some global functions. If an xtra is loaded, its global functions are added to the normal Lingo functions and available for you to call from your code.

With FileIO as an example:

fPath = getOSDirectory();

FileIO's getOSDirectory global function returns the path to the system directory.

Dot Syntax

If you are coming from Lingo, you may still be using the older syntax with instanced xtras:

instance = new(xtra "fileio")

p = displayOpen(instance)

You must use the new dot syntax in JavaScript:

instance.methodName(argument)

instance = new xtra("fileio");

fPath = instance.displayOpen();

Case

Xtra methods are case-sensitive in JavaScript. If you use the wrong case for an xtra's method you will get a "[methodname] not defined" error.

Lingo Data Types not Native to JavaScript

Some xtras require parameters or return values in data types not directlly supported by JavaScript. JavaScript does not natively support Lingo lists or symbols, but Director has methods for allowing JS to access these data types.

Symbols

You can store Lingo symbols returned from an Xtra call in a JavaScript variable. You can create a Lingo symbol from a string to pass as an argument to an Xtra with the following.

a = symbol( "cat" );

#cat

Lists

Lingo lists are similar to JavaScript arrays, except that their indexing starts at 1, not 0. There are two kinds of Lingo lists - linear and property. Linear lists just contain values while property lists contain property / value pairs.

Linear list

[ "dog",5, #chinese]

Property list

[ #pet: "dog", #age: 5, #race: #chinese ]

The following functions create and modify Lingo lists from JavaScript

Linear list

linearList = list()

linearList.add("dog")

linearList.add(5)

linearList.add(symbol("chinese"))

linearList

<["dog", 5, #chinese]>

linearList[1]

dog

linearList[1] = "turtle"

linearList

<["turtle", 5, #chinese]>

Property list

myPropList = propList()

myPropList.addProp(symbol("pet"),"dog")

myPropList.addProp(symbol("age"),5)

myPropList.addProp(symbol("race"),symbol("chinese"))

myPropList

<[#pet: "dog", #age: 5, #race: #chinese]>

myPropList["pet"]

dog

myPropList[1]

dog

myPropList.getPropAt(1)

#pet