AccordionContainer

Like StackContainer and TabContainer, an AccordionContainer holds a set of panes whose titles are all visible, but only one pane's content is visible at a time. Clicking on a pane title slides the currently-displayed one away, similar to a garage door.

Examples

For this example, we'll show the lazy-loading feature of panes. Lazy loading defers the loading process until the pane is actually displayed. Since Dojo does this with XHR, you can only load panes that reside on the server from which the original content came. We'll use a test pane provided with Dijit. You can download this file from the nightly build at http://svn.dojotoolkit.org/dojo/dijit/trunk/tests/layout/tab1.html. For the example to work verbatim, just place it in the same directory as this file on your web server.

Nunc consequat nisi vitae quam. Suspendisse sed nunc. Proin ...

More content

• One
• Two
• Three

Accessibility

Keyboard

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

Introduction

1. Dojo: What is It?
2. History
3. What Dojo Gives You

[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.

Resizing and Layouts

Involved Mixins

Your widget will have to have dijit._Contained mixed in, and dijit._Container if you plan to put other widgets inside of it. Being a container means that the getChildren function will be available to you for use when passing down the resize events.

How Layout Widgets Communicate

A container will call the resize function on its contained widgets (that should also be its direct children to avoid ambiguous layout). They might pass a size object, and the conditions in which they will are outlined below.

2 Modes of Positioning

In many browsers, an easy method of making a block node fill up the entire area of its parent container (parent container referring to any node positioned using the relative or absolution value) is to position it absolutely, and set its top, right, bottom, and left positions to 0. This isn't true for all browsers or all nodes. Because of this, it can be confusing knowing how your resize function should work.

The resize Function

If you receive a size object (which has t, l, w, and h properties representing top, left, width, and height) then it probably means that your layout has encountered a situation in which CSS is no longer capable of handling positioning. What this means is that you'll have to alter this object according to the unique properties (most likely padding and offsets) before passing the value to contained widgets. You'll also use this object to size the widget's node using either dojo.marginBox as a setter, or setting the style properties directly.

If you don't receive a size object, it probably means that you can make adjustments using only CSS. For example, if you change the style attribute top in this situation, the height automatically changes, while in non-CSS mode, you would probably end up pushing your node down, without its height changing.

ContentPane

A Content Pane is the most basic layout tile. Conceptually, it's like the content boxes in portals like MyYahoo. A content pane resembles an iframe, but contains extra design features, fits in with the current theme, and renders widgets properly.

You can use content panes by themselves, but usually you will place content panes inside of a layout container. For example, in a tabbed layout, content pane tags surround each tab of information.

Examples

Simple content panes have their content inside the tags Most of the time, these simple panes are used inside layout containers, so the examples in LayoutContainer, StackContainer and TabContainer illustrate their use.

Linked content panes, those with their content in a separate URL, are useful even without containers. To illustrate, we'll use the example data store countries.txt, which you can download below (after this page text, and right above the navigation bars). For the example to work verbatim, just place it in the same directory as these files on your web server. If the following is linked_content_pane.html:

You can include it within a page like this. Because the tree may take a long time to load, we display a loading message for the user.

This text be replaced with the tree

Note here that the dojo.require for the tree is placed in the calling html. SCRIPT tags of type "text/Javascript" in the included html file are ignored. However SCRIPT tags with type dojo/method and dojo/connect work fine. See Understanding the Parser for details.

Like all Dijit components, you can create a ContentPane dynamically. The following example adds a new ContentPane to an existing Tab Container.

NOTE! You must include a sourcenode when creating a ContentPane. You must call .startup() after you have addChild() it to your parent

Accessibility - updated for 1.0

General Issues

The developer is responsible for determining if the ContentPane should be in the tab order of the page or not. If the ContentPane is not likely to have a focusable item within the contents, the developer may want to add tabindex=""0" onto the ContentPane element. This will put the ContentPane into the tab order so if someone is using the tab key to navigate through the elements on the page, the ContentPane itself will get focus. Having focus go to the ContentPane itself can be helpful for users of assistive technology to be able to navigate to an area that may not have any focusable elements within it such as a preview pane for mail messages or a page footer containing important information.

LayoutContainer

Similar to a layout pane in Java AWT and Delphi, a LayoutContainer is a box with a specified size (like style="width: 500px; height: 500px;"), that contains children widgets marked with "layoutAlign" of "left", "right", "bottom", "top", and "client". It takes it's children marked as left/top/bottom/right, and lays them out along the edges of the box, and then it takes the child marked "client" and puts it into the remaining space in the middle.

Left/right positioning is similar to CSS's "float: left" and "float: right", and top/bottom positioning would be similar to "float: top" and "float: bottom", if there were such CSS.

Note that there can only be one client element, but there can be multiple left, right, top, or bottom elements.

Examples

A Layout Container easily formats a table of contents:

The Dojo Book

Table of Contents

Introduction

1. Dojo: What is It?
2. History
3. What Dojo Gives You

To change the drawing order:

The LayoutContainer goes through the children as specified, and each child is laid out into the "remaining space", where "remaining space" is initially the content area of this widget, but is reduced to a smaller rectangle each time a child is added. So, changing the order of the children will change how they are laid out.

Table of Contents

The Dojo Book

Introduction

1. Dojo: What is It?
2. History
3. What Dojo Gives You

SplitContainer

Contains multiple children widgets, all of which are displayed side by side (either horizontally or vertically); there's a bar between each of the children, and you can adjust the relative size of each child by dragging the bars. You must specify a size (width and height) for the SplitContainer.

Example

Sizing

sizeShare

Setting the sizeShare attribute on any child widgets of a SplitContainer sets the initial relative size of that widget, either its height or width depending on the layout of the SplitContainer. The value of sizeShare is not a percentage or a pixel measure. Its value is relative to other child widgets of the same SplitContainer. So, for example, given four child widgets and each having a sizeShare attribute of 25, would evenly divide the SplitContainer into four parts. However, giving each a sizeShare attribute of 10 or 1 would achieve the same result, as the values are computed relative to each other - they do not have to add up to 100.

sizeMin

Setting the sizeMin attribute on any child widget of a SplitContainer defines the smallest size, in pixels, that the child widget will be changed to. The value is specified as an integer, without "px" appended to it.

Accessibility (added for 1.0)

Keyboard

In Dojo 1.0 there is no keyboard mechanism to resize the split container. In Firefox the content panes within a split container will be in the tab order (this is default FF behavior) so if the data is not visible, the user can use the arrow keys to scroll the data into view. This allows keyboard access to all of the data and thus accessibility requirements are met by default in Firefox. IE does not include the content pane in the tab order. If there is a chance that all of the data will not being visible within a pane of a split container, a tabindex=0 should be included in the markup of the inner content pane to ensure keyboard accessibility in both Firefox and IE.

StackContainer

A container that has multiple children, but shows only one child at a time (like looking at the pages in a book one by one). This container is good for wizards, slide shows, and long lists or text blocks.

Examples

Here's a freely pageable document.

< >

This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below.

As used herein, "this License" refers to version 3 of the GNU Lesser General Public License, and the "GNU GPL" refers to version 3 of the GNU General Public License. "The Library" refers to a covered work governed by this License, other than an Application or a Combined Work as defined below.

You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL.

Indication of the current child

.dijitStackController .dijitToggleButtonChecked button {
    background-color: white;
    background-image: none;
}
.dijit_a11y .dijitStackController .dijitToggleButtonChecked button {
    border-style: dashed !important;
}

Accessibility

Keyboard

TabContainer

A TabContainer is a container that has multiple panes, but shows only one pane at a time. There are a set of tabs corresponding to each pane, where each tab has the title (aka label) of the pane, and optionally a close button.

Examples

Here's a Grimm set of tabs, indeed.

Once upon a time there was a dear little girl who was loved by every one who looked at her, but most of all by her grandmother, and there was nothing that she would not have given to the child.

Hard by a great forest dwelt a poor wood-cutter with his wife and his two children. The boy was called Hansel and the girl Gretel. He had little to bite and to break, and once when great dearth fell on the land, he could no longer procure even daily bread.

There was once upon a time a hermit who lived in a forest at the foot of a mountain, and passed his time in prayer and good works, and every evening he carried, to the glory of God, two pails of water up the mountain.