MutationEvent object (Object/DOM)

A notification that the document content has changed should trigger a mutation event which is described in one of these objects.

Availability:

DOM level - 2
JavaScript - 1.5
Netscape - 6.0
JavaScript syntax:NmyMutationEvent = new MutationEvent()
Object properties:attrChange, attrName, bubbles, cancelable, currentTarget, eventPhase, newValue, prevValue, relatedNode, target, timeStamp, type
Class constants:ADDITION, MODIFICATION, REMOVAL
Object methods:initEvent(), initMutationEvent(), preventDefault(), stopPropagation()

The availability of the MutationEvent object handling can be determined with the Implementation.hasFeature() method call.

These event types are enumerated in the DOM level 2 specification and are:

The DOM level 2 event module specification doesn't describe the binding of these events to event handlers so although this event model is implemented in Netscape 6.0, you may need to explore the event naming conventions to make effective use of it. Taking the event names and placing the 'on' prefix in front of them and using that as a property name to which you can attach a handler function may work. The DOM level 2 event module also provides an EventListener registration which allows you to register event types with EventTarget objects, using the addEventListener() method.

The contextual information is carried in the detail property, and when it is present, will usually describe a reference to a node object or an attribute value.

When the document content is modified, a MutationEvent object is instantiated to carry a description of that change to the event handler.

Mutation events cannot be cancelled. This is because the DOM interface would become unwieldy if the document changes were not properly completed. This may change later when the DOM standard introduces transaction handling although the DOM level 2 event specification does not go to great lengths to explain in detail how that is likely to be implemented.

A cascading effect is very likely with a single DOM tree change causing a number of subsequent mutation events to be fired as lower portions of the tree are affected. The standard doe not mandate any particular ordering of these events and leaves it to the implementation to control the sequence. This suggests that the cascaded mutations may occur in a different sequence depending on the browser. You should therefore design your event handler so that it can be called in a re-entrant and random order and that there should be no dependency on things being traversed in a predictable sequence.

See also:DOM, DOM - Level 2, DOM Events, Event management, Event model, Event-driven model, EventListener object, EventTarget.addEventListener(), Implementation.hasFeature()

PropertyJavaScriptJScriptNIEOperaNESECMADOMCSSHTMLNotes
attrChange1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/aReadOnly.
attrName1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/aReadOnly.
bubbles1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-
cancelable1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-
currentTarget1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-
eventPhase1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-
newValue1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/aReadOnly.
prevValue1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/aReadOnly.
relatedNode1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/aReadOnly.
target1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-
timeStamp1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-
type1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-

MethodJavaScriptJScriptNIEOperaNESECMADOMCSSHTMLNotes
initEvent()1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-
initMutationEvent()1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-
preventDefault()1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-
stopPropagation()1.5 1.5 n/a6.0 6.0 n/a n/a n/a n/a2 2 n/a n/a-