The blank web page is the empty canvas on which you paint your application. Your brush is HTML markup, and your paint is the various widgets available to you. But layout without structure is chaos. We need a way to organize the visual elements of our site into a form that has meaning. The various layout widgets provided by Dojo give us that structure by providing organized containers into which we pour our content. In this chapter, we explore the various layout widgets provided in Dijit and try to understand the proper use of each.
For many years, the standard technique for laying out a web page was to create a table with rows and cells that would contain the content. Each page element or widget could be placed in a single table cell, and by adjusting the height and width of the cells, the designer could create exactly the look that she desired. As the Cascading Style Sheet (CSS) specification evolved, it became possible to define layout with CSS properties, and the use of tables became much less common. But as Ajax techniques became more popular, and more sophisticated user interfaces became the norm for web sites, it was more and more necessary to find ways to make working with groups of page elements easier. One technique was to group elements into <DIV> tags. The <DIV> could be treated as a single page element and moved, hidden, or styled in a single step. In effect, the <DIV> tag could act as a container that could hold other elements including complete widgets. Instead, we’ll use a special Dojo widget, which will act as a container for other widgets.
The community of user interface developers has already developed a set of patterns for containers in desktop applications. For instance, one of the most useful patterns involves allowing child widgets to be placed in a container and automatically positioned to the top, bottom, left, or right sides of the container. This is known as the BorderLayout container in the Java AWT toolkit, and similar counterparts exist in many other GUI environments. In addition to this layout container, a number of other types of containers were also common in desktop applications.
Dojo provides layout container widgets that implement many of the patterns common in desktop user interfaces. In this chapter we explore those widgets. Let’s start by examining the common features shared by the various layout containers. As we examine each of the Dojo container widgets, keep in mind that they contain children, which may themselves be other container widgets. The most typical child widget is a ContentPane, which can contain any arbitrary content—which is why we look at that one first.
The first thing to keep in mind when discussing the properties and methods of LayoutWidget is that it is a subclass of dijit._Widget, so any widget created from this class also inherits all the properties and methods of dijit._Widget. See Chapter 6, “Introduction to Dojo Widgets,” to review those properties and methods.
Additionally, dijit.form._LayoutWidget has its own properties and methods and also inherits methods and properties from dijit._Container and dijit._Contained. These are the properties and methods we are going to review now.
Much of the functionality derived from the layout widgets actually resides in the widgets that they contain. Layout widgets are the gift boxes that contain the widgets that we wish to use. Like a box, one of the most important aspects of a layout container is simply how large it is. We’ll see that reflected in the properties that allow us to define the size and placement of a layout container.
The reason that size is such an important consideration for containers is that the size of the container constrains the size of the child widgets that are displayed within the container. Usually, HTML works in the opposite way. In other words, most DOM elements expand to the size of the DOM elements that they contain. But a Dojo container generally will occupy a fixed portion of the page regardless of how large its children are.
The primary properties for a layout widget define its height and width and its position. However, these are style properties not properties of the widget object itself. So you should define them the way you would define other CSS properties, using stylesheets, named styles or by adding them as a style property of the widget tag itself as shown:
style="width=95%; height=200px; left=50px; top=75px"
Other properties are inherited from dijit._Widget. Remember that inheritence allows the object to contain all of the properties and methods of its superclass. For a refresher on the dijit._Widget class, review Chapter 6.
Table 8.1 describes the key methods for dijit.layout._LayoutWidget. As discussed before, these are not necessarily all the methods, just the ones that are most likely to be useful to a developer.
Table 8.1. Methods in dijit.layout._LayoutWidget
Method | Description |
|---|---|
| This method will change the size of the layout container and then redisplay it by running the The
|
| Return the child widget before the current widget without setting focus to that widget. |
| Return the child widget after the current child widget without setting focus to that widget. |
| Add a child widget to the container. |
| Remove the child widget specified in the argument as widget from the container. |
| Return a collection of children of the container. |
| Return |
| Change the focus to the child widget that is just after the widget currently having focus. |
| Change the focus to the child widget that is just before the widget currently having focus. |
| Set the focus to the child widget specified in the parameter widget. |
Except for resize, the methods involve selecting children widgets of the container.
Now that we’ve reviewed the properties and methods that are a part of all layout container widgets, let’s review the specific container widgets available to us in Dojo. We use the same format for explaining each widget that was described in Chapter 7, “Dojo Form Widgets.”
dijit.layout.ContentPane | |
Super Classes | |
File Location | dijit/form/ContentPane.js Use |
Usage | This class creates a simple container for content. The content can be any HTML elements or Dojo widgets. It acts like a
The really powerful feature of this widget is that content can be loaded dynamically from the server using either a property when the widget is created or running a method after the widget is created. See the Key Properties and Key Methods sections for more detail. |
Display Examples |
This figure shows a |
HTML Markup Examples | Create a new <div dojoType="dijit.layout.ContentPane"
style="width: 100%; height: 150px;">
<div id="c1" dojoType="dijit.layout.ContentPane">
First Widget
</div>
<div id="c2" dojoType="dijit.layout.ContentPane"
href="dynamic.html">
</div>
<div id="c3" dojoType="dijit.layout.ContentPane">
Third Widget
</div>
</div> |
JavaScript Constructor Examples | The following code will create a content pane and attach it to an existing DOM element. cp = new dijit.layout.ContentPane( {}, dojo.byId("d1"));
cp.setContent('<b>Miscellaneous Content</b>'),Note that the |
Key Properties | |
Key Methods | |
Key Styles | |
Key Events | |
Notes | None |
dijit.layout.LayoutContainer | |
Super Classes | |
File Location | dijit/form/LayoutContainer.js Use |
Usage | This class will create a widget that provides compartments for holding content. The compartments can be formatted using alignment properties. This is most like the traditional use of the |
Display Examples |
In the figure, each of the content blocks is a |
HTML Markup Examples | Create a LayoutContainer widget with all five positions in it containing content. <div dojoType="dijit.layout.LayoutContainer"
style=" height: 150px;">
<div id="c1" dojoType="dijit.layout.ContentPane"
layoutAlign="left">
Left Content
</div>
<div id="c2" dojoType="dijit.layout.ContentPane"
layoutAlign="right">
Left Content
</div>
<div id="c3" dojoType="dijit.layout.ContentPane"
layoutAlign="top">
Top Content
</div>
<div id="c4" dojoType="dijit.layout.ContentPane"
layoutAlign="bottom">
Bottom Content
</div>
<div id="c5" dojoType="dijit.layout.ContentPane"
layoutAlign="client">
Client Content
</div>
</div> |
JavaScript Constructor Examples | The following code will create a new layout = new dijit.layout.LayoutContainer( {}, dojo.byId("d1"));
menu = new dijit.Menu();
menuItem1 = new dijit.MenuItem({label: "Item 1"});
menu.addChild(menuItem1);
layout.addChild(menu);Note: Although we’re adding a menu in this example, we could be adding any arbitrary content. |
Key Properties | None |
Key Methods | None |
Key Styles | None |
Key Events | None |
Notes | None |
dijit.layout.SplitContainer | |
Super Classes | |
File Location | dijit/form/SplitContainer.js Use |
Usage | This class creates a widget that contains child widgets separated by a bar that can be dragged by using the mouse to change the relative sizes of the space allocated for the children. Although the children can be widgets of any type, it is typical that they are themselves other containers. |
Display Examples |
This screenshot shows a SplitContainer widget with three widgets as its contents. The child widgets are separated by a slider bar which can be moved by the use to change the relative amount of space allocated for each child. |
HTML Markup Examples | Create a <div id="outer"
dojoType="dijit.layout.SplitContainer"
style="width: 100%; height: 150px;"
persist="false"
activeSizing="false">
<div id="c1"
dojoType="dijit.layout.ContentPane"
sizeShare="10">
First Widget
</div>
<div id="c2"
dojoType="dijit.layout.ContentPane"
sizeShare="20">
First Widget
</div>
<div id="c3"
dojoType="dijit.layout.ContentPane"
sizeShare="30">
First Widget
</div>
</div> |
JavaScript Constructor Examples | The following code will create a new container = new dijit.layout.SplitContainer( {} );
content1 = new dijit.layout.ContentPane({} );
container.addChild(content1);
content2 = new dijit.layout.ContentPane({} );
container.addChild(content2);Note: We would still need to add content to each of the |
Key Properties | |
Key Methods | |
Key Styles | None |
Key Events | None |
Notes | It is necessary that you supply a size and width value for the |
dijit.layout.StackContainer | |
Super Classes | |
File Location | dijit/form/StackContainer.js Use |
Usage | Creates a widget that can display different panes of content by stacking the hidden content and providing a control the user can click to display the hidden content. This widget only displays one child at a time. An associated widget called |
Display Examples |
Notice that the |
HTML Markup Examples | Create a <span dojoType="dijit.layout.StackController" containerId="sc">
</span>
<div id="sc" dojoType="dijit.layout.StackContainer"
style="width: 100%; height: 90px;">
<div id="c1" dojoType="dijit.layout.ContentPane"
title="widget 1">
First Widget</div>
<div id="c2" dojoType="dijit.layout.ContentPane"
title="widget 2">
Second Widget</div>
<div id="c3" dojoType="dijit.layout.ContentPane"
title="widget 3">
Third Widget</div>
</div>
</div>Notice that the |
JavaScript Constructor Examples | The following code will create a new container = new dijit.layout.StackContainer( {} );
content1 = new dijit.layout.ContentPane({} );
container.addChild(content1);
content2 = new dijit.layout.ContentPane({} );
container.addChild(content2);Note: We would still need to add content to each of the |
Key Properties | None |
Key Methods | None |
Key Styles | None |
Key Events | None |
Notes | None |
dijit.layout.AccordionContainer | |
Super Classes | |
File Location | dijit/form/AccordionContainer.js Use |
Usage | Creates a widget that can display different panes of content by stacking the hidden content and providing a control the user can click to display the hidden content. Most layout containers can contain children of any content type. However, this widget must have children of type This widget contains children of type |
Display Examples |
Notice that the Pane Control Icon is different depending on whether the pane is open or closed. Only one pane may be open at a time. The user can click anywhere on the pane control to open it (not just on the icon). |
HTML Markup Examples | Create a new <div id="sc" dojoType="dijit.layout.AccordionContainer"
duration="25">
<div id="c1" dojoType="dijit.layout.AccordionPane"
title="Pane 1">
<p style="padding:20px">First Widget</p></div>
<div id="c1" dojoType="dijit.layout.AccordionPane"
title="Pane 2">
<p style="padding:20px">Second Widget</p></div>
<div id="c1" dojoType="dijit.layout.AccordionPane"
title="Pane 3">
<p style="padding:20px">Third Widget</p></div>
</div> |
JavaScript Constructor Examples | The following code will create a new container = new dijit.layout.AccordionContainer( {} );
content1 = new dijit.layout.AccordionPane({} );
container.addChild(content1);
content2 = new dijit.layout.AccordionPane({} );
container.addChild(content2);Note: We would still need to add content to each of the |
Key Properties | |
Key Methods | |
Key Styles | None |
Key Events | None |
Notes | None |
dijit.layout.TabContainer | |
Super Classes | |
File Location | dijit/form/TabContainer.js Use |
Usage | This class creates a widget that acts as a container for Remember, the content for the tabs is also dynamic and can be retrieved from the server using an Ajax request when the tab is selected and the |
Display Examples |
Notice that in the first example, the Tab 3 has a special icon (a dark circle with a white X) that allows the user to close the tab so that it completely disappears from the page. |
HTML Markup Examples | Create a <div id="sc1"
dojoType="dijit.layout.TabContainer"
style="width: 100%; height: 10em;">
<div dojoType="dijit.layout.ContentPane" title="Tab 1">
First Content Pane
</div>
<div dojoType="dijit.layout.ContentPane" title="Tab 2">
Second Content Pane
</div>
<div dojoType="dijit.layout.ContentPane" title="Tab 3">
Third Content Pane
</div>
</div> |
JavaScript Constructor Examples | The following code will create a new container = new dijit.layout.TabContainer( {} );
content1 = new dijit.layout.ContentPane({} );
container.addChild(content1);
content2 = new dijit.layout.ContentPane({} );
container.addChild(content2);Note: We would still need to add content to each of the |
Key Properties | |
Key Methods | |
Key Styles | None |
Key Events | None |
Notes | None |
Now we can turn our attention to some of the special widgets that don’t fall into the categories we’ve already reviewed. These are some of the most powerful and interesting widgets that Dojo provides. So fasten your seatbelt and get ready!