A set of key/value pairs representing measurements of various dimensions of an element.

Overview

The Element.Layout class is a specialized way to measure elements. It helps mitigate:

• The convoluted steps often needed to get common measurements for elements.
• The tendency of browsers to report measurements in non-pixel units.
• The quirks that lead some browsers to report inaccurate measurements.
• The difficulty of measuring elements that are hidden.

Usage

Instantiate an Element.Layout class by passing an element into the constructor:

var layout = new Element.Layout(someElement);

You can also use Element.getLayout, if you prefer.

Once you have a layout object, retrieve properties using Hash's familiar get and set syntax.

layout.get('width');  //-> 400
layout.get('top');    //-> 180

The following are the CSS-related properties that can be retrieved. Nearly all of them map directly to their property names in CSS. (The only exception is for borders — e.g., border-left instead of border-left-width.)

• height
• width
• top
• left
• right
• bottom
• border-left
• border-right
• border-top
• border-bottom
• padding-left
• padding-right
• padding-top
• padding-bottom
• margin-top
• margin-bottom
• margin-left
• margin-right

In addition, these "composite" properties can be retrieved:

• padding-box-width (width of the content area, from the beginning of the left padding to the end of the right padding)
• padding-box-height (height of the content area, from the beginning of the top padding to the end of the bottom padding)
• border-box-width (width of the content area, from the outer edge of the left border to the outer edge of the right border)
• border-box-height (height of the content area, from the outer edge of the top border to the outer edge of the bottom border)
• margin-box-width (width of the content area, from the beginning of the left margin to the end of the right margin)
• margin-box-height (height of the content area, from the beginning of the top margin to the end of the bottom margin)

Caching

Because these properties can be costly to retrieve, Element.Layout behaves differently from an ordinary Hash.

First: by default, values are "lazy-loaded" — they aren't computed until they're retrieved. To measure all properties at once, pass a second argument into the constructor:

var layout = new Element.Layout(someElement, true);

Second: once a particular value is computed, it's cached. Asking for the same property again will return the original value without re-computation. This means that an instance of Element.Layout becomes stale when the element's dimensions change. When this happens, obtain a new instance.

Hidden elements

Because it's a common case to want the dimensions of a hidden element (e.g., for animations), it's possible to measure elements that are hidden with display: none.

However, it's only possible to measure a hidden element if its parent is visible. If its parent (or any other ancestor) is hidden, any width and height measurements will return 0, as will measurements for top|bottom|left|right.