views:

43

answers:

2

Hi there,

I am a C/C++ programmer, and I am currently playing with some Javascript code, and I am having problems finding where the documentation is for the standard Javascript libraries that are available in the browser.

Specifically, I am setting an onload callback function on a HTMLImageElement, created with new Image(). I also want to read about the src property, since it has non-standard behavior - when this property is assigned to, the image is reloaded.

Mozilla has some skeleton documentation of the various attributes here: https://developer.mozilla.org/en/DOM/Image There is no documentation here, only a list of properties. The onload property is not mentioned. The src property is listed but there is no documentation on it.

MSDN has has better documentation: http://msdn.microsoft.com/en-us/library/cc197055(VS.85).aspx.

My question is 'where are the standard docs'? Is Image() a global variable, or is it a property of window the global object? Who writes the API for window and document? Is there a standard, or does each browser just copy each other?

A: 

I guess the standard is written by the W3C.

http://www.w3.org/TR/REC-DOM-Level-1/

You may find also the standards for DOM Level 2 and 3 ;)

Golmote
+3  A: 

The DOM is actually a separate thing to JavaScript. The DOM can be accessed from other languages, such as VBScript in IE. And general-purpose programming languages like Java, Python, PHP etc have their own non-browser-based DOM libraries.

The basic DOM operations that work on both HTML and general XML documents can be found in DOM Core; HTML documents get extra methods defined in DOM HTML. These are the latest ‘levels’ of support defined by W3; not all browsers support everything in DOM Level 3 Core. But DOM Level 1 Core is pretty much solid.

Confusingly, DOM HTML has further developed, but not in its own DOM specification. Instead it is part of HTML5. This standardises a lot of extensions that were already widely supported in browsers, like innerHTML, and adds a bunch more stuff that isn't widely implemented yet (and may be changed before the document is standardised).

The DOM is only the document object model: it specifies what you get inside the document object. It doesn't specify other browser features, like the contents of window. The browser object model (BOM) was previously unstandardised; HTML5 is making the first effort to properly document it.

HTML5 also specifies parts of the browser object model (BOM) that were not previously standardised. Stuff like window that isn't directly connected to the document content.

The upshot of all this is that there isn't a single document you can go to that will tell you everything about what methods and properties you have available to you in web scripting. Some day DOM Core plus HTML5 will cover it all, but today HTML5 includes a lot you can't rely on, and isn't exactly the most readable of guides even by the standards of standards documents. So yes, I'm afraid you're going to have to continue to check MDC and MSDN for popular support.

Is 'Image' a global variable, or is it a property of 'window' the global object?

Image is specified by HTML5 to be a member of the window object, which, being the global context, allows you to refer to it as just Image... that's not quite the same thing as being a global variable, but it's close enough for most.

It is a constructor-function that returns a DOM object implementing the HTMLImageElement interface (from DOM Level 1 HTML, extended in HTML5). It was originally introduced in Netscape 3.0 as a mechanism for pre-loading images; plus already-created images could be accessed from document.images to change their src. Today new Image() doesn't do anything different to document.createElement('img').

I also want to read about the 'src' property, since it has non-standard behavior - when this property is assigned to, the image is reloaded.

Well the image won't be reloaded necessarily, but it may cause the load event to be fired on some browsers. Unfortunately this isn't standardised (even in HTML5 as far as I can see). IE, Firefox and Opera fire load on every src set (even if the src is not changed) whereas WebKit (Chrome/Safari) only ever fires it on the initial image load.

This sort of thing is why there are sites with big tables of differing browser behaviours, and why we still have to actively test on different browsers.

bobince