Class DOM2Flavor

Defined in flavors.js

DOM2Flavor uses an XML Namespace aware DOM2 implementation with createElementNS, and the DOM2 events model for handling events.

Among possibly other things, this turns XBLinJS into a direct replacement for XBL proper, usable with Mozilla's XUL. DOM2Flavor's constants are preloaded with a couple values that will help with this, including setting XUL's namespace as the default. You may want to change this in your code.

Field Detail

flavorConstants

Object flavorConstants

flavor constants for DOM2

The flavor constants are as follows:

• defaultURI: The default URI to use for creating elements that do not have a colon in their name. This can be extremely useful as it becomes possible to use many HTML-based widgets in XUL by setting their defaultURI to the XHTML URI, http://www.w3.org/1999/xhtml. However, this defaults to the XUL URI for easy XUL Widget creation, http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul.

namespaces

Object namespaces

Namespaces storage for registerNamespace

This stores the namespaces declared with registerNamespace. By default, this starts with "xul" set to the XUL namespace, and "html" set to the XHTML namespace (http://www.w3.org/1999/xhtml), and "svg" set to the SVG namespace (http://www.w3.org/2000/svg), but you can add more.

This stores the namespaces as mnemonic->URI, i.e., html: "http://www.w3.org/1999/xhtml".

DOM2Flavor

DOM2Flavor()

DOM2Flavor - XBLinJS flavor for use with XUL applications

attachHandlerToNode

void attachHandlerToNode(node, event, handler)

Attach an event handler to a node

This uses the addEventListener interface defined by the DOM2 event model to add the event handler XBLinJS creates.

In XUL, there is still some distinction between displayed nodes and non-displayed nodes; displayed nodes can have events bound to them via node.onclick = function (){} type syntax, but nodes not yet added to a document can only have event bindings added via addEventHandler. Reading the standard indicates that being able to use node.onclick at all is a non-standard bonus from the Mozilla people (probably added to shut up complaints from old-school Javascript programmers used to the HTML model), as that is defined as HTML 4.0 event listeners which doesn't apply at all to XUL, which even when using HTML is actually using XHTML.

Note that there is some overlap with XBLinJS's event model and what DOM2 provides, but there are some differences as well; probably the most noticable is the XBLinJS does guarantee an event processing order, which allows for some applications not possible (or at least not safe) under the standard DOM2 Event model. A notable lack is that XBLinJS has no clean support for event capturing. However, I think in practice this will turn out unnecessary. If I am wrong about this, please report it and we will look into addressing the problem cleanly; I don't feel confident I can hack up a good solution without a real-world use case.

Note also that there could be wildly entertaining interactions with the standard DOM event model if, in addition to using Widget event specifications, you addEventListeners to widget-owned DOM nodes. If you are confident you understand both the DOM event model and the XBLinJS event model, the interactions should be well defined, but in general, I'd have to say I advise against mixing the two on the same DOM nodes.

createElement

Object createElement(nodeType)

create an element

This uses document.createElementNS. You have to register namespaces with the widget to use their mnemonic, like "xhtml:". See registerNamespace.

getAttributeFrom

Object getAttributeFrom(node, key)

Gets the attribute from a node, be it Widget or DOM node

Corresponding to .setAttribute, this just uses .getAttributeNS.

getElementsByTagName

Object getElementsByTagName(tagName, node)

registerNamespace

void registerNamespace(mnemonic, URI)

Registration function for namespaces

This function registers namespaces for use in createElement and its derivatives.

Note it directly writes DOM2Flavor.prototype.namespaces, so A: you can call it directly without a Widget reference via DOM2Flavor.prototype.registerNamespace() like any other function and B: If you override the namespaces object in a subclass, this function will stop working unless you provide a fixed function in that subclass.

Typically, you'll put this somewhere in your code as a simple function call, not something in a widget. It doesn't hurt to register a namespace over and over again, but it does no good, either.

Parameters:
mnemonic - The name of the namespace, as used before the colon in the tagName, i.e., "html" or "xul".
URI - The URI of the namespace.

setAttributeOn

Object setAttributeOn(node, key, value)

Set attribute on the node, be it widget or DOM node

This, like createElement, uses setAttributeNS. For better or for worse, if a namespace is not given, the .defaultURI is used. The pain of this should be somewhat ameliorated by the fact that defaultURI can be set on a Widget-by-Widget basis, so hopefully in practice this is not annoying.