Laying out Enhanced Elements

CSS is very powerful when it comes to laying out the page, but you will invariably want to mix in behavior with the element layout. Enhanced Elements allow you to do this.

Any element with a role attribute can be enhanced. E.G. To enhance elements with role="presentation" register a handler

function enhance_presentation(el,role,config) { }
Resolver("roles").declare("handlers.enhance.presentation", enhance_presentation);

The function will be passed the element, the role name, and config collected from the elements data-role attribute and the pages application/config scripts.

If the enhance function depends on functionality that isn't yet available it should return false. In that case enhance will be attempted again when the page loading has progressed.

Once enhanced the function should return the object or data related to the enhanced element, which will be passed to layout and discard as the instance. If nothing is returned the element will be flagged enhanced without an associated instance.

Register a layout handler

Enhanced elements

function layout_presentation (el,layout,instance) 
{

Resolver("roles").declare("handlers.layout.presentation", layout_presentation);

Resize callback

When the page is resized or adjacent elements will be notified with the new dimensions.

You should throttle the layout handler so resizing will only be done so often. When resizing the browser updates are sent of every pixel change to give the smoothest user experience. Throttling gives you a balance between visual feedback and overall system performance.

PresentationLoader.layout_presentation = function(el,layout,instance) 
{
    if (typeof instance != "object") return;
    
    if (layout.displayed == false) {
        if (layout.oldDisplayed == true) instance.onHide();
        layout.oldDisplayed = layout.displayed;
    } else {
        if (layout.oldDisplayed == false) instance.onShow();
        layout.oldDisplayed = layout.displayed;
        
        instance.onResize(el.offsetWidth,el.offsetHeight);
    }
};
PresentationLoader.layout_presentation.throttle = 250;

By adding a throttle property to the layout handler function calls will not come until the time in milliseconds have elapsed after the previous call.

The layout object has several attributes

name	use
width	Visible width of the block. (offsetWidth)
height	Visible height of the block. (offsetHeight)
contentWidth	Width of the content, might be larger than width (scrollWidth)
contentHeight	Height of the content, might be larger than height (scrollHeight)
area
displayed	Boolean indicated if the content is displayed

Sizing Content

Before the layout for enhanced elements with a role or a layouter is adjusted, the content of laidout elements is calculated to inform the sizing.

Sizing Enhanced Elements

Maintained Content

After elements are sized the maintained elements are laid out if flagged as queued.

Maintaining Enhanced Elements