BorderContainer (1.1)

New in 1.1

This widget is a container partitioned into up to five regions: left (or leading), right (or trailing), top, and bottom with a mandatory center to fill in any remaining space. Each edge region may have an optional splitter user interface for manual resizing. Note that there can be at most one child marked for each region.

Sizes are specified for the edge regions in pixels or percentage using CSS -- height to top and bottom, width for the sides. You might specify a top region of height:100px and a left region of width:50%. The center typically does not have any dimensions specified in CSS and resizes automatically to fill the remaining space.

BorderContainer operates in a choice of two layout modes: the design attribute may be set to "headline" (by default) or "sidebar". With the "headline" layout, the top and bottom sections extend the entire width of the box and the remaining regions are placed in the middle. With the "sidebar" layout, the side panels take priority, extending the full height of the box.

A simple layout with design="headline": (demo not functional yet)

The Dojo Book
Table of Contents



/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
            "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Layout Container Demo 2</title>
    <style type="text/css">
        @import "http://o.aolcdn.com/dojo/1.1/dijit/themes/tundra/tundra.css";
        @import "http://o.aolcdn.com/dojo/1.1/dojo/resources/dojo.css"
    </style>
    <script type="text/javascript" src="http://o.aolcdn.com/dojo/1.1/dojo/dojo.xd.js"
        djConfig="parseOnLoad: true"></script>
    <style> 
        /* NOTE: for a full screen layout, must set body size equal to the viewport. */
        html, body { height: 100%; width: 100%; margin: 0; padding: 0; }
    </style>
    <script type="text/javascript">
        dojo.require("dojo.parser");
        dojo.require("dijit.layout.ContentPane");
        dojo.require("dijit.layout.BorderContainer");
     </script>
</head>
<body class="tundra">
<div dojoType="dijit.layout.BorderContainer" design="headline">
   <div dojoType="dijit.layout.ContentPane" region="top" style="background-color:red">
        The Dojo Book
   </div>
   <div dojoType="dijit.layout.ContentPane" region="left"
        style="background-color:lightblue;width: 120px;">
        Table of Contents
    </div>
    <div dojoType="dijit.layout.ContentPane" region="center"
        style="background-color:yellow">
            <blockquote><a href="../node/717">Introduction</a>
                <ol>
                    <li><a href="../node/718">Dojo: What is It?</a></li>
                    <li><a href="../node/719">History</a></li>
                    <li><a href="../node/733">What Dojo Gives You</a></li>
                </ol>
                </blockquote>
    </div>
</div>       
</body></html>

[TODO: sidebar demo]

Splitters can be enabled on any of the regions, except the center, by setting the "splitter" attribute on the child widget to true. "minSize" and "maxSize" attributes on the regions can specify constraints for the splitter in pixels. The "liveSplitters" attribute on the BorderContainer enables behavior where the splitter actively resizes the regions as the user moves the mouse. If set to false, the resize will only occur on mouse up.

[TODO: splitter demo]

The "persist" attribute makes it possible for the widget to remember the splitter positions from one session to the next using cookies.

BiDi considerations

Because this widget is BiDi aware, "leading" or "trailing" terminology may be used to indicate that the layout should be flipped horizontally for right-to-left rendering. "left" and "right" are absolute positions and will be unaffected by text direction.

Accessibility (a11y)

The children of BorderContainer must be listed in their natural tab order.

1.0 Migration Tips

This widget replaces the functionality of LayoutContainer and SplitContainer. The most important things to note when migrating your code from these widgets are:

  • LayoutContainer.layoutAlign attribute corresponds to BorderContainer.region
  • What LayoutContainer called the "client" region, BorderContainer calls "center"
  • There must be at least one child marked as region="center"
  • sizeShare is no longer supported. Specify the pane sizes using CSS instead as pixels or percentages.

Unlike LayoutContainer, BorderContainer does not allow for multiple widgets to be placed in a given position (e.g. inner left and outer left, patterned after Delphi) In order to achieve this, nested BorderContainers must be used.

Also, while you can specify sizes in percentages, these are only initial sizes, so setting left and right to 33% will split the children across into thirds, but resizing will allow the center to grow or shrink while the sizes remain fixed. There currently is no widget to provide equal layout, although HTML Tables may serve this purpose.