I'm reading the 1.0 Spec, section 5.4, where the properties of the object being returned from $sf.ext.geom() are explained.
The properties in the documentation are: win, self and exp. However, in the SafeFrame reference implementation I'm also seeing a "par" property, for which I assume it stands for "parent". Why is there a "par" property in the reference implementation, but not in the spec? Did I miss something?
The 'par' property represents the parent DOM element in the host page of the iFrame that is the SafeFrame. It was not part of the formal spec, but during implementation we needed calculations from the parent DOM tree to understand if there were clip or overflow style rules that would cause the ad expansion to be affected.
The reference implementation and spec were being developed concurrently. In the spec we were shooting for minimal invasiveness and perscriptiveness in order to get V1 ratified. I would just classify this as an implementation detail that didn't get fed back into the spec.
Let me clarify that a bit more. . .
"par" is obviously a rectangle. What it represents is relative to the page construction.
"par" represents the parent element of the SafeFrame that is acting as the "viewport".
So for example a SafeFrame tag placed directly in the page, has a "par" rectangle representing the document body, since the body is the viewport. Effectively in this case it just means the browser window.
Sometimes though a SafeFrame is placed within a scrolling div element (with overflow set to auto/scroll). In that case said div element becomes the owning viewport, and that element is used to generate "par".
The "exp" property is a psuedo rectangle that is then calculated based on the relationship between the "par" and "self" properties, which of course tells you how much in each direction you can expand.
The relationship between "par" and "self" is also used of course in the calculation of viewability.
We didn't document that property b/c we have other other properties their that are more useful to end users. And of course implementers could put other properties there as well, as it's just a simple JS object and doesn't have it's own constructor per se.
That said, I do think it's probably good we document that. . .
Well, I'm trying to expand to fill the current visual viewport, and I was only able to do that by calculating values from exp, par and self. Is there any other way?
I wouldn't want to rely on an undocumented property that either not all vendors will provide or will define different the values to.