x_ite_dom has been adopted by the main x_ite.js library (https://github.com/andreasplesch/x_ite_dom/issues/40). Therefore all development shifted to
https://github.com/create3000/x_ite/blob/main/src/x_ite/Browser/DOMIntegration.js
This repo will remain, for documentation purposes.
x_ite_dom.js is intended to be used with the X3D browser x_ite.js (https://github.com/create3000/x_ite), up to version 7.0.0. x_ite_dom links the X3D DOM nodes to the X3D scene graph and thereby allows for control of the X3D scene using regular DOM manipulation methods. Please be aware that X3D requires a well defined organisation of the scene. If modifying the DOM results in an invalid scene graph, errors result.
The design is based around the idea that x_ite_dom.js is an optional, thin bridge layer which only requires minimal or no modification to x_ite as a X3D browser. To a large extent it tries to use the external SAI as it is defined for standard conforming X3D browsers.
The overall idea is to use the DOM mutation observer facility to relay changes in the DOM to the X3D scene graph which is internal to x_ite. After creating an initial X3D scene from X3D XML under the X3DCanvas tag, the bridge code installs a mutation observer to catch all changes within a Scene element. Depending on what was changed, then X3D SAI as well as some internal x_ite.js methods are invoked to realize these changes within the parallel scene graph.
A design goal is to keep the code lines count small enough to keep all code in a single file. If the code base grows larger, I would not be able to support development, and it would indicate that there are too many features.
See index.xhtml and the examples in tests/ and tests/html5 for usage of the code.
Since X3D uses an XML encoding, xhtml encoded web pages are preferred. Regular html case-insensitive encoding can be used as well but is less well tested.
Event handling currently covers all inputOutput and outputOnly fields, which includes all sensor and interpolator events.
Mouse events originate from x3d sensor nodes. This means that the x3d scene has to have such a sensor node (TouchSensor) for any mouse events to be dispatched.
See tests/interactiveTransformations.xhtml and other for examples.
Event type names parallel x3d field names. The name construction is "x3d" + "_" + x3d event name.
This means the usual events such as 'click' or 'mouseover' are not available. However, there are similar events for x3d sensors albeit with other names (for example x3d_isOver).
The onevent attributes or properties are not available. Use element.addEventListener() instead.
The event parameter provided to the callback function has these properties:
The dispatched events do not bubble back up, eg. usually there should be no need to stop propagation. The event listeners should be attached to the specific DOM elements which is the dispatch target of the event.
To help with attaching listeners to sensors within inlines, a new 'x3dload' event is dispatched on the document target to signal when all inlines per scene are appended to the document.
To help with debugging x3d event flow, a 'trace' attribute for the X3DCanvas element enables detailed logging of output events to the console. This is particularly helpful for ROUTE, Interpolator and event utility debugging. Since all output events are logged, tracing impacts performance. Remove the trace attribute to switch off.