The root of the DOM tree about which the listener should listen to changes.
The root of the DOM tree about which the listener should listen to changes.
Produces the calls for the added/removed family of events.
The event name.
The node added or removed.
The parent of this node.
A list of call specs.
Handles node deletions.
The event.
Utility function for calling event handlers.
The handler.
The arguments to pass to the handler.
Produces the calls for children-... events.
The type of call to produce.
The parent of the children that have changed.
The children that were added.
The children that were removed.
Node preceding the children.
Node following the children.
A list of call specs.
Handles node deletion events.
The event.
Produces the calls for included/excluded family of events.
The event name.
The node which was included or excluded and for which we must issue the events.
The parent of this node.
A list of call specs.
Handles node additions.
The event.
Processes pending triggers.
Sets a timeout to run the triggers that must be run.
Handles attribute change events.
The event.
Handles text node changes events.
The event.
Adds an event handler or a trigger handler. Note that if you want to add a trigger handler, the first argument must be a single string, due to how the 2nd argument is interpreted.
When adding an event handler, this argument is a CSS selector. When adding a trigger handler, this argument is a trigger name.
Note that the meaning of the selector parameter for text-changed
events is different than the usual. Whereas for all other handlers, the
selector matches the element parameter passed to the handlers, in
the case of a text-changed event the selector matches the
parent of the node parameter.
The handler to be called by this listener when the events
specified in eventTypes occur.
Clear anything that is pending. Some implementations may have triggers delivered asynchronously.
Process all changes immediately.
Start listening to changes on the root passed when the object was constructed.
Stops listening to DOM changes.
Tells the listener to fire the named trigger as soon as possible.
The name of the trigger to fire.
Generated using TypeDoc
This class models a listener designed to listen to changes to a DOM tree and fire events on the basis of the changes that it detects.
An
included-elementevent is fired when an element appears in the observed tree whether it is directly added or added because its parent was added. The opposite events areexcluding-elementandexcluded-element. The eventexcluding-elementis generated before the tree fragment is removed, andexcluded-elementafter*.An
added-elementevent is fired when an element is directly added to the observed tree. The opposite events areexcluding-elementandremoved-element.A
children-changingandchildren-changedevent are fired when an element's children are being changed.A
text-changedevent is fired when a text node has changed.An
attribute-changedis fired when an attribute has changed.A
triggerevent with name[name]is fired whentrigger([name])is called. Trigger events are meant to be triggered by event handlers called by the listener, not by other code.Example
Consider the following HTML fragment:
<ul> <li>foo</li> </ul>If the fragment is added to a
<div>element, anincluded-elementevent will be generated for<ul>and<li>but anadded-elementevent will be generated only for<ul>. Achanged-childrenevent will be generated for the parent of<ul>.If the fragment is removed, an
excluding-elementandexcluded-elementevent will be generated for<ul>and<li>but aremoving-elementandremove-elementevent will be generated only for<ul>. Achildren-changingandchildren-changedevent will be generated for the parent of<ul>.The order in which handlers are added matters. The listener provides the following guarantee: for any given type of event, the handlers will be called in the order that they were added to the listener.
Warnings:
Keep in mind that the
children-changed,excluded-elementandremoved-elementevents are generated after the DOM operation that triggers them. This has some consequences. In particular, a selector that will work perfectly withremoving-elementorexcluding-elementmay not work withremoved-elementandexcluded-element. This would happen if the selector tests for ancestors of the element removed or excluded. By the time the-edevents are generated, the element is gone from the DOM tree and such selectors will fail.The
-edversion of these events are still useful. For instance, a wed mode in use for editing scholarly articles listens forexcluded-elementwith a selector that is a tag name so that it can remove references to these elements when they are removed. Since it does not need anything more complex thenexcluded-elementworks perfectly.A listener does not verify whether the parameters passed to handlers are part of the DOM tree. For instance, handler A could operate on element X so that it is removed from the DOM tree. If there is already another mutation on X in the pipeline by the time A is called and handler B is called to deal with it, then by the time B is run X will no longer be part of the tree.
To put it differently, even if when an event is generated element X was part of the DOM tree, it is possible that by the time the handlers that must be run for that mutation are run, X is no longer part of the DOM tree.
Handlers that care about whether they are operating on elements that are in the DOM tree should perform a test themselves to check whether what is passed to them is still in the tree.
The handlers fired on removed-elements events work on nodes that have been removed from the DOM tree. To know what was before and after these nodes before they were removed use events that have
previous_siblingandnext_siblingparameters, because it is likely that the nodes themselves will have both theirpreviousSiblingandnextSiblingset tonull.Handlers that are fired on children-changed events, and which modify the DOM tree can easily result in infinite loops. Care should be taken early in any such handler to verify that the kind of elements added or removed should result in a change to the DOM tree, and ignore those changes that are not relevant.