“Live” vs “Loaded” DOM
One of the potentially confusing aspects of HDi is the notion of the "live" and "loaded" DOMs. The "DOM" is the "Document Object Model", and you can read more about it at https://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/core.html -- basically it is an in-memory representation of an XML document.
Really there is nothing special about these two things; the spec just needed a way to differentiate between "stuff that was loaded from disc" and "stuff that is currently animating" when talking about specific features, and these two names were chosen.
To be clear, there is only one DOM per markup page, and it contains all the elements and attributes of the markup page. The difference is that the "loaded" DOM refers to the nodes accessible through the W3C APIs (those linked to above), whilst the "live" DOM refers to the animated properties of elements that are extensions of W3C.
The Loaded DOM (aka "W3C APIs")
Using the W3C APIs, you can query the initial value of an element's attributes (ie, the value it was "loaded" with), and you can also update those values if you like (through the getAttributeNS and setAttributeNS methods). You can also add and remove elements from the DOM to dynamically change the structure of the document (using the appendChild and removeChild methods). Note that due to the way style sheets are processed, elements added to the DOM via W3C APIs typically need to reference a pre-defined style in order to appear on-screen (eg, <button style="someDefinedStyle"> ) although the attributes can be over-ridden by animation.
The Live DOM (aka "Animated Element APIs")
Using the additional APIs defined by HDi, you can query the currently-animated value of any attributes (ie, the "live" value) and in many cases update the value immediately (using property set syntax) or schedule an animation over time (using the animateProperty method). The Animated Element APIs have no way to add or remove elements; only properties can be accessed. They also don't allow access to arbitrary attributes; only the ones defined in the HD DVD spec appear through these APIs.
Why the Dichotomy?
Both the initial (loaded) value of an element and the currently-animated value are important. Sometimes you want to know where an element is right now, sometimes you want to know where it started. Sometimes you want to animate an element in real-time; sometimes you want to reset its "at rest" value.
Elements in HD DVD have what are called "property blocks," which is really just a fancy way of saying that each attribute (property) has up to four values at any one time, in increasing order of importance:
- Its initial (or "at-rest") value originally computed when the page was loaded
- Its modified XML value stored in the W3C DOM
- Its currently-animated value via the markup engine
- Its currently-animated value via script
Also the performance implications of having to update the full XML DOM on every clock tick were rather onerous and didn't really provide any value. So the DOM stays the same whilst the property blocks get animated.
What about document.load()?
HDi has an API called document.load that re-interprets the W3C DOM, starts the page clock again, and shows the markup page to the user. When you call load, any currently animated values are thrown away, and any changes you made to the DOM via W3C APIs get reflected in the page. Basically in terms of the list above, #1 is replaced by #2 while #3 and #4 get deleted.
An Example
You can play with the attached sample to see how these three things interact. Click on the set and unset buttons in each category to see what the final result will be. The demo looks like this:
The red buttons manipulated the W3C DOM, the green buttons perform markup animations, the blue buttons perform script animations, and the purple button is just the thing being animated. Hopefully by playing around and setting / unsetting various things you can see how the priority system works.
