Layout
HTML and Layouts
Typically HTML has bottom-up sizing, where a container is as big as it's contents, so that given
inner1 is big enough to hold the text "Part 1", inner2 is big enough to hold the text "Part 2", and outer is big enough to hold the divs. And if outer is bigger than the browser's viewport, the browser window displays a scrollbar. The web page you're reading now uses that layout, and unless your monitor is 3 feet tall (in which case, we envy you!) you see the scrollbar on the right.
But for some web pages, you want them to work with the opposite pattern, where you start with a given size, typically the browser viewport, and then partition it into smaller sections. This is the way desktop application look, for example a mail program that has a tree on the left, a list of messages in the upper right, and the message preview on the lower right.
Note that in this scenario, there's no scrollbar on the browser window itself, but if any pane is too small to display all the text it contains then it gets a scrollbar.

Layout like the picture above can be done using tables or fancy CSS (see recent A List Apart article about CSS sizing), but that technique has it's limits... it doesn't allow things like tabs or accordions or split containers where the user can adjust the size of each pane.
Dijit Layout
Dijit has a number of layout widgets which can be combined in a hierarchy to achieve that. Every layout widget contains a list of other layout widgets, except for the "leaf" nodes in the hierarchy, which are typically ContentPanes.
How does this work in practice? You need to think about the application above in a top-down (or outside-in) way:
- the screen is split into two parts. The top is a toolbar and
- the bottom is split into a left section and right section
- the left section has three panes one of which is shown at a time
- the right section is split into two parts, a list of messages and a preview pane.
Conceptually it's a set of containers like this:

There are three types of elements in that picture:
- containers that display all their children side by side
- containers that display one child at a time
- leaf nodes containing content
#1 is either LayoutContainer or SplitContainer. A LayoutContainer is used when all but one of the elements is a constant size. (In this case, the toolbar is a constant size and the the bottom section takes the rest of the screen, so we will use a LayoutContainer for that, and SplitContainers for the other parts.
#2 is AccordionContainer, TabContainer, or StackContainer. They all do basically the same thing, but look different.
#3 is typically ContentPane but could be any widget. An important consideration is whether or not the widget's size is adjustable (like a ContentPane) or not (like a Toolbar). See #1 above.
So keeping those rules in mind and picking which widgets to use it will look like:
- LayoutContainer
- Toolbar
- Horizontal Split Container
- Accordion Container
- ContentPane #1
- ContentPane #2
- ContentPane #3
- Vertical Split Container
- Content Pane #4
- Content Pane #5
- Accordion Container
And then from there it's easy to convert to HTML. Starting from the outside:
<div dojoType="dijit.Toolbar" layoutAlign="top">...</div>
<div dojoType="dijit.layout.SplitContainer" orientation="horizontal" layoutAlign="client">
see below
</div>
</div>
Note that the layoutAlign arguments on the child nodes are actually processed by the parent, but the other arguments are processed by the child. A bit confusing but that's the way it works.
The split container will look like:
(left part)
<div dojoType="dijit.layout.AccordionContainer">
<div dojoType="dijit.layout.AccordionPane" title="Mail">...</div>
<div dojoType="dijit.layout.AccordionPane" title="News">...</div>
<div dojoType="dijit.layout.AccordionPane" title="Alerts">...</div>
</div>
(right part, see below)
</div>
And on the right... since you want to split the screen vertically the SplitContainer would actually contain another SplitContainer:
<div dojoType="dijit.layout.AccordionContainer">
<div dojoType="dijit.layout.AccordionPane" title="Mail">...</div>
<div dojoType="dijit.layout.AccordionPane" title="News">...</div>
<div dojoType="dijit.layout.AccordionPane" title="Alerts">...</div>
</div>
<div dojoType="dijit.layout.SplitContainer" orientation="vertical">
<div dojoType="dijit.layout.ContentPane" title="Table">...</div>
<div dojoType="dijit.layout.ContentPane" title="Preview">...</div>
</div>
Tips
Sizing to browser viewport: To make the outermost layout widget size to the browser's viewport, in your page CSS you should have:
width: 100%; height: 100%;
border: 0; padding: 0; margin: 0;
}
where mainDiv is the id of the outermost div.
Note that height=width=100% means different things depending on the browser when you have padding or border, so when using those tags it's best not to have either of those. Put your padding, border, and margin on elements inside the outer layout container.
Restrictions about visibility: none of the layout widgets work if they are inside a hidden element. This is very important and a mistake many people make.
Startup call: when building widgets programmatically, you create the parent first, then add the children, and grandchildren... and finally call startup(). Startup() is called once on the top element in the hierarchy, after the whole hierarchy has been setup and the element inserted.
Accordion Container In this container, panes are pulled up or down like window blinds by clicking the pane title. Only one shows in full at a time. |
![]() |
Border Container (new in 1.1) Partitions container into top/left/bottom/right/center sections with optional splitter controls so the user can adjust the dimensions. Useful (for example) to reserve the top 100px of the screen for title and navigation, and then the rest of the viewport for the contents. Note how in this case there would be just one scrollbar on the contents, rather than on the browser window itself. |
![]() |
Content Pane the leaves in the hierarchy. Contains arbitrary HTML. |
![]() |
Layout Container (deprecated in 1.1) Arranges children into top/left/bottom/right/client sections. Useful (for example) to reserve the top 100px of the screen for title and navigation, and then the rest of the viewport for the contents. Note how in this case there would be just one scrollbar on the contents, rather than on the browser window itself. |
![]() |
Split Container (deprecated in 1.1) Splits the children into sections where user can adjust the size of each section (making one section bigger makes others smaller) | ![]() |
Stack Container base class for TabContainer and AccordionContainer but allowing for user defined display to control which pane is shown |
![]() |
Tab Container Like tabbed folders in a desk drawer, you click on a title tab to bring the corresponding pane to the front. |
![]() |
Attachment | Size |
---|---|
border_container.png | 11.04 KB |
- Printer-friendly version
- Login or register to post comments
- Unsubscribe post
Be advised!
I was going crazy with pages completely blanking out during browser window resizes, opening Dialog widgets, and expanding the Firebug pane in Firefox. This was all solved as soon as I put the css from the "Sizing to browser viewport" tip above.
It seems this suggestion is not so much a tip as a requirement!
Re: Be advised
Yep, you need to set the outer sizing in some fashion. The tip is just one way though. You don't have to do it in exactly that way- for instance I have a page now where I use the following (insignificant stuff elided) to get a layout that is centered and 80% of the viewport width:
body {
width: 100%; height: 100%;
border: 0; padding: 0; margin: 0;
align: center;
}
html {
width: 100%; height: 100%;
background-color: #DDEEFF
}
#mainDiv {
width: 80%; height: 100%;
border: 0; padding: 0; margin: 0;
background-color: white;
margin-left:auto; margin-right:auto;
}
AccordianContainer nested in a Dialog widget does not work.
we need something which behaves like a Dialog Widget and inside the Dialog widget we need to have AccordianContainer widget. But when we make AccordianContainer as child of Dialog widget, Dialog widget functions fine but the AccordianContainer inside Dialog widget gives wierd script errors.
please use trac for bugs
trac.dojotoolkit.org login=guest/guest
thanks
Above example needs to be rewritten for BorderContainer
The mail example can be mocked up (and actually has been rewritten in 1.1) with one less layer in the hierarchy by using a BorderContainer with splitters rather than separate horizontal/vertical split containers. It should also be noted that LayoutContainer and SplitContainer have been deprecated as of the 1.1 release.