Dojo: The Definitive Guide

StackContainer

A StackContainer is a layout dijit that displays a sequence of tiles one at a time. A StackContainer is conceptually just like a slideshow in which you can page backward and forward through a "stack" of tiles. Like LayoutContainer, you provide any number of child widgets to the StackContainer, and it takes care of the display. In its most basic usage, you simply page through the available tiles, as shown in Example 14-4.

Example 14-4. Creating a StackContainer in markup

<div id="stack" dojoType="dijit.layout.StackContainer"
  style="width:100px; height:100px; margin:5px; border:solid 1px;">

    <div dojoType="dijit.layout.ContentPane">
        One fish...
    </div>
    <div dojoType="dijit.layout.ContentPane">
        Two fish...
    </div>
    <div dojoType="dijit.layout.ContentPane">
        Red fish...
    </div>
    <div dojoType="dijit.layout.ContentPane">
        Blue fish...
    </div>

</div>

<button dojoType="dijit.form.Button">&lt;
    <script type="dojo/method" event="onClick" args="evt">
        dijit.byId("stack").back(  );
    </script>
</button>

<button dojoType="dijit.form.Button">&gt;
    <script type="dojo/method" event="onClick" args="evt">
        dijit.byId("stack").forward(  );
    </script>
</button>

The usual container and generic layout methods apply to StackContainer; additionally, you should also note the features in Table 14-6.

Table 14-6. StackContainer API

Name (default)	Type	Comment
doLayout	Boolean	Used to change the size of the currently displayed child to match the container's size. true by default.
selectedChildWidget	Object	References the currently selected child widget. null by default.
selectChild(/*Object*/ page)	Function	Used to select a specific child widget.
forward( )	Function	Used to page forward to the next child widget.
back( )	Function	Used to page backward to the previous child widget.

Tip

The StackContainer also supports several additional features:

• A closeChild(/*Object*/ child) method

• An onClose( ) extension point

• Children may exhibit the closeable, title, and selected attributes

• Topics that are published when children are added, removed, or selected, <id>-addChild, <id>-removeChild, and <id>-selectChild, respectively

Because these features are most commonly associated with the TabContainer (which inherits from StackContainer), however, their formal introduction will be delayed until the next section.

If you've followed along with the previous example of programmatically creating layout dijits, Example 14-5 should seem awfully familiar.

Example 14-5. Programmatically creating a StackContainer

var container = new dijit.layout.StackContainer({}, "foo");

var leftChild = new dijit.layout.ContentPane({});
leftChild.domNode.innerHTML="page 1";

var rightChild = new dijit.layout.ContentPane({});
rightChild.domNode.innerHTML="page 2";

container.addChild(leftChild);
container.addChild(rightChild);

container.startup(  );

/* Skip from page 1 to page 2 with... */
dijit.byId("foo").forward(  );

Procrastination (a.k.a. Lazy Loading) May Yield Better Performance

The previous example uses explicit buttons for paging, but it is not uncommon to use a StackContainer as an application container to control the flow of an application with multiple pages. For example, your application might initially display a page with a search bar; once a button is pressed to trigger a search, you might page forward to display a search results screen. Assuming that you've defined every page of the application as a child of a StackContainer, this approach has the advantage of never explicitly reloading a page—a little bit of snazzy flare for a Web 2.0 style interface.

Although loading the entire application at one time when the page loads may be the best option for some circumstances, you could also elect to lazy-load content by configuring a child ContentPane to lazy load via its href attribute. Recall that this behavior is controlled by a ContentPane's preload attribute, which when false (the default) does not fetch content until it becomes visible. You can watch the Firebug console to confirm this behavior. For example, if the URL referenced below, which is entitled blueFish contained the text "Blue fish . . . " from Example 14-4, then the following adjustment would lazy load the fourth page of the StackContainer:

<div dojoType="dijit.layout.ContentPane" href="blueFish"></div>

Lazy loading is ideal for situations in which there may be application features that are essential, but not often used. A preferences pane is a prime candidate for lazy loading that often involves gobs of controls that may not appear on any other page of the application.