New JavaScript Features in Atlas PR2

NOTE: This is preliminary documentation of new JavaScript features in the current Navigator beta (Atlas PR2), provided for the benefit of the developer community. In the future, these sections will be improved and integrated in the body of the JavaScript Guide.

Summary

Language features

• Array objects
• The typeof operator
• Object prototypes
• New string object features
• Math.random works on all platforms

• Determining installed plug-ins
• Java-JavaScript communication
• Image reflection and event handlers
• Form element type property
• focus and blur methods for windows
• Ability to cancel events in onClick
• Ability to call event handlers explicitly
• Modifiable select objects

These are new features of the JavaScript language itself, and will ultimately apply to both client and server JavaScript. (Note: these JavaScript features are not in the current LiveWire beta)

Arrays

There is now a special object type, called Array, that you can define instances of with the new operator. Once you have an array, you can assign values to its elements, just as you would any variable. For example,

    var a = new Array()
    a[0] = "hi"
    a[99] = "world"
    if (a.length == 100)	// This is true, because defined a[99] element.
       document.write("The length is 100")

    var a = new Array(100)

You can't set the length property explicitly by assignment. However, as shown in the above examples, you can set length by an explicit argument to a constructor, or implicitly by setting an indexed property where the index is greater than or equal to the previous length value.

Finally, if you want to construct a "dense" array of two or more elements starting with index 0, and you have initial values for these elements, you can call the Array constructor with arguments for the element values. (A dense array is one in which each element has a value.) For example,

    var a = new Array("foo", bar, 3.14159)

The typeof operator

The typeof operator returns a string telling the type of its unevaluated operand. For example,

    typeof foo == "undefined"	// where foo is undefined
    typeof eval == "function"
    typeof null == "object"
    typeof 3.14 == "number"
    typeof true == "boolean"
    typeof "a string" == "string"

String object features

String objects are now "real" objects. You normally construct strings literally by quoting some characters, and if you want to use them as objects, you follow a string reference with .length or .indexOf("sub"), as if it were an object. Now, you can make string objects using new:

    var s = new String("hello")

These strings are reference-counted and may be passed among scripts in different windows or frames without any "weak link" corruption problems that affected Navigator 2.0, and which required the workaround of adding the empty string to another window's string to "import" it:

    var mys = otherWindow.s + ""    // 2.x: import other window's string
    var mys = otherWindow.s         // 3.x: ok, strong link works

Object prototypes

JavaScript now explicitly allows you to extend all objects after you create them with the new operator. This applies to built-in constructors such as Date and String, as well as user-defined object types.

Set the value of objType.prototype.propName to define a property that is shared by all objects of the specified type, where objType is the object type (the name of the constructor function) and propName is the name of the property.

    var s1 = new String("a"), s2 = new String("b")

    // add a repeat-string-N-times method to all strings:
    function str_rep(n) {
        var s = "", t = this.toString()
        while (--n >= 0) s += t
        return s
    }

   String.prototype.rep = str_rep    // add a rep() method to String

    s1.rep(3) == "aaa"
    s2.rep(5) == "bbbbb"

    var s3 = new String("c")
    s3.rep(2) == "cc"

    function fake_rep(n) { return "repeat " + this + " n times." }
    s1.rep = fake_rep
    s1.rep(1) == "repeat a 1 times."

    s2.rep(4) == "bbbb"		// still works!
    s3.rep(6) == "cccccc"

This works with user-defined objects too:

function Car(make, model, year) {
    this.make = make
    this.model = model
    this.year = year
}

Car.prototype.wheels = 4        // no 3-wheelers please!

var mine = new Car("Acura", "Integra", 1987)

if (mine.wheels == 4)        // true!
   document.write("Car has ", mine.wheels, " wheels.")

Indexing object properties

When you define an object's properties with property names, you cannot refer to these properties by their ordinal index, as you could in Navigator 2.0. This applies when you create an object and its properties with a constructor function, as in the above example of the Car object type, and when you define individual properties explicity (for example, myCar.color = "red").

If you define object properties initially with an index, for example,

myCar[5] = "25 mpg"

The rule is: if you initially define a property by its name, you must always refer to it by its name. If you initially define a property by an index, you must always refer to it by its index.

The exception to this rule is objects reflected from HTML: for example, the frames, forms, elements, and anchors arrays. You can always refer to these objects by their ordinal number (based on where they appear in the document) and by their name (if defined). For example, you can refer to the second form in a document as document.forms[1] or as document.myform, if the second FORM tag has a NAME attribute of "myform".

Random number function

The Math.random() method now works on all platforms. The random number generator is seeded from current time, as in Java.

These are new or improved features of client JavaScript.

Image reflection and event handlers

Images defined by the IMG tag are now reflected in JavaScript. All images in a document are in an array called document.images, and the number of images in a document is document.images.length. So, for example, you refer to the first image in a document as document.images[0], the second image as document.images[1], and so on.

Each image object has properties for the IMG attributes:

Property Name	Reflection of
src	SRC attribute: URL of the image file. This is the only required attribute.
lowsrc	LOWSRC attribute: URL of the low-resolution image file.
height, width	HEIGHT, WIDTH attributes: height and width of image in pixels (read-only).
border	BORDER attribute: width of image border in pixels (read-only).
vspace, hspace	VSPACE, HSPACE attributes: horizontal and vertical space in pixels (read-only).
complete	Boolean value that indicates whether Navigator has completed its atttempt to load the image (read-only).

The position and size of an image in a document are set when the document is displayed in Navigator. However, you can set the src and lowsrc properties to change the image displayed.

Setting the src attribute has the side-effect of actually starting to load the new URL into the image area (and aborting the transfer of any image data that is already loading into the same area). Therefore, if you're going to alter the lowsrc property, you need to do so before setting the src property. If the URL in the src property references an image that is not the same size as the image cell it is loaded into, the source image is scaled to fit.

There are three event-handlers for images:

• onload: script to execute when image is loaded.
• onerror: script to execute if there is an error loading the image.
• onabort: script to execute if user aborts loading the image (by clicking a link, clicking the Stop button, and so on.)

    var w = window.open()
    if (w != null && w.opener == null)
        w.opener = window

myform.userChoice.options[i].text = myform.textField.value;