DOM API
ADsafe gives guest code a controlled document interface instead of a raw DOM node.
Selection stays inside the widget
The dom object passed to a widget's startup callback represents its permitted subtree. Its q method selects nodes and returns a wrapper called a bunch. A bunch can represent no nodes, one node, or several nodes.
Queries resemble CSS selectors, but use ADsafe's own query language. A tag query such as dom.q('p') selects matching paragraphs within the widget. Do not assume an arbitrary browser CSS selector is accepted.
Operate through a bunch
A bunch exposes operations without handing the guest code the underlying browser nodes. Selection, updates and event handlers remain behind that interface. The following snippets describe separate operations; they are not executed here.
// Select paragraphs within the widget.
var paragraphs = dom.q('p');
// Replace their text through the wrapper.
paragraphs.value('A bounded update.');
// Listen through the interface.
paragraphs.on('click', function () {
paragraphs.value('A click was received.');
});Why the wrapper matters
A raw browser node has relationships to its owner document and the surrounding tree. A restricted language alone is insufficient if an API returns an object that leads outside the intended boundary. The historical API therefore mediates the objects and operations available to guest code.
Read the reference with its version
The original documentation includes query selectors, bunch setters and getters, text nodes and events. Method behaviour depends on the runtime version. Check the original API documentation against the historical runtime source when studying an example.
For a current browser-isolation discussion, read JavaScript widget boundaries.