YUI Layout-Based Wireframes

Overview

YUI layout-based wireframes address complex user interface requirements in web applications, especially when supporting a wide range of browsers, including legacy versions. These wireframes enable fluid layouts that use the full viewport, allow widgets to resize dynamically, and support user-driven resizing with persistent preferences. The YUI Layout Manager provides a robust JavaScript-based solution for these needs, offering features such as nested layouts, resizable elements, and automatic scrollbar rendering.

YUI Layouts: Structure and Behavior

A YUI layout, or wireframe, is a structured container with up to five units: top, right, bottom, left, and center. The center unit is always present and occupies the remaining space not used by the other units. The framework manages initial width and height constraints for each unit.

You can attach a wireframe to the body element to fill the entire viewport or to a specific element with defined dimensions. When the viewport resizes, the wireframe and all nested wireframes automatically adjust to fit the new boundaries.

Each wireframe and unit corresponds to a DOM element, identified by its id attribute. To prevent ID collisions in composite environments where components may be reused, the YuiId concept is used. YuiId enables reliable element lookup within the layout framework.

YuiId: Purpose and Usage

A YuiId provides a consistent way to resolve elements by ID, supporting both direct @id references and contextual @yui:id references within an ancestor's @id scope.

Direct reference: Uses the standard getElementById method. This approach does not support reuse within the same DOM tree due to potential ID conflicts.
Contextual reference: Uses a combination of ancestor and local IDs, allowing safe reuse of components without collisions.

Example

Consider an AjaxPanel with the following HTML:

<div wicket:id="root">
  <div class="container"
    <div yui:id="top">[ Top unit ]</div>
  </div>
</div>

Wicket generates a unique ID for the root element, such as rootAA. To reference the 'Top unit' div, the YuiId becomes rootAA:top. If the panel is reused elsewhere and the root ID changes (e.g., to rootZZ), the YuiId updates to rootZZ:top, ensuring correct element resolution. Use the following function to resolve elements by YuiId:

YAHOO.hippo.Dom.resolveElement(YuiId);

This function is provided by the YUI hippodom module.

Wireframe Rendering Process

When rendering a wireframe, the framework creates a new node structure inside the root element to represent the wireframe and its unit containers. It then moves the unit elements into their respective containers.

Example

Initial structure:

<div id="root">
  <div id="top">[ Top ]</div>
  <div id="center">[ Center ]</div>
</div>

After rendering, the structure becomes:

<div id="root" class="yui-layout">
  <div class="yui-layout-doc">
    <div class="yui-layout-unit yui-layout-unit-top">
      ..
        <div id="top">[ Top ]</div>
      ..
    </div>
    <div class="yui-layout-unit yui-layout-unit-center">
      ..
        <div id="center">[ Center ]</div>
      ..
    </div>
  </div>
</div>

The ellipses (..) represent additional elements added by YUI for size management, scrollbars, and borders.

To integrate YUI layouts with Wicket, a client-side manager component handles the wireframe's lifecycle, rendering, and resizing. For implementation details, refer to the inline documentation in layoutmanager-debug.js.

Configuration Example

The following example demonstrates how to configure a YUI wireframe and the corresponding HTML structure.

Configuration

/application:
  jcr:primaryType: frontend:plugin
  plugin.class: org.hippoecm.frontend.plugins.cms.Main
  wicket.id: service.main
  wicket.behavior: service.behavior.main.layout
  wicket.extensions: [extension.top, extension.center]
  extension.top: service.application.top
  extension.navigator: service.application.center
/mainLayout:
  jcr:primaryType: frontend:plugin
  plugin.class: org.hippoecm.frontend.plugins.yui.layout.WireframePlugin
  behavior.id: service.behavior.main.layout
  units: [left, center]
  /yui.config:
    jcr:primaryType: frontend:pluginconfig
    center: id=main-center,body=main-center-body,minWidth=400
    left: id=main-left,body=main-left-body,resize=true,minWidth=300,width=400

HTML Structure

<html xmlns:wicket="http://wicket.apache.org/"
      xmlns:yui="http://www.hippoecm.org/frontend/yui">
  <wicket:panel>
    <div wicket:id="main">
      <div yui:id="main-left">
        <div yui:id="main-left-body">
          <div wicket:id="extension.left">[Left unit]</div>
        </div>
      </div>
      <div yui:id="main-center">
        <div yui:id="main-center-body">
          <div wicket:id="extension.center">[Center unit]</div>
        </div>
      </div>
    </div>
  </wicket:panel>
</html>

This configuration enables a flexible, resizable layout with left and center units, each supporting nested content and persistent user-driven resizing.