Microsoft AJAX Library: Sys.UI.DomElement Remarks

The library offers pretty basic DOM manipulation, but it’s beta than nothing. The add-, remove-, toggle- , and containsCssClass are straightforward. Things get interesting when it comes to positioning.

getLocation (element)

This function gets the absolute position of an element, as documentation states. The important point is it doesn’t matter if an element is positioned via the position: absolute CSS rule or not. You get (x, y) coordinates relative to the browser upper left corner, even if the page is scrolled.

Documentation also says, for example, that x is “the number of pixels between the element and the left edge of the parent frame.” This clarification makes sense considering that every frame has a life of its own.

Note: getLocation is “not supported for elements that have fixed positioning (style='position:fixed')” (see documentation).

setLocation (element, x y)

Even though getLocation and setLocation sound like a getter and setter, it is not so. setLocation simply positions an element via the position: absolute CSS rule. From then on, it’s a different ball game, and unfortunately the documentation doesn’t point it out.

To quote Eric Meyer,

“When an element is positioned absolutely, it is completely removed from the document flow. It is then positioned with respect to its containing block, and its edges are placed using the offset properties (top, left, etc.). […]

“Whatever space the element might have occupied in the normal document flow is closed up, as though the element does not exist. […]

“The containing block for an absolutely positioned element is the nearest ancestor element that has a position value other than static.”

It is critical to understand the definition of a containing block. If an element happens to have an ancestor with position: relative or position: absolute, it becomes its containing block. Therefore the element is positioned x and y pixels away from the upper left corner of the containing block.

With no containing blocks on its way, an element is positioned relative to the document itself, which–in majority of cases—is the expected result.

Here’s a bit of sound advice from The JavaScript Anthology:

“There are so many possible combinations of nested positioning and browser differences that it’s almost impossible to write a script that takes them all into account. If you are working with an interface that uses a lot of relative or absolute positioning, it’s probably easiest to experiment with specific cases and write special functions to deal with them.”

getBounds (element)

This function returns the absolute (x,y) coordinates of an element via getLocation and also calculates its width and height.

The DomElement cheat sheet has a diagram and an example which demonstrate how padding, borders and scroll bars are lumped together to produce the final height and width measurements.