Using the Dojo BorderContainer to design application layouts
The ArcGIS JavaScript API samples provide a great way to learn how to use specific mapping and analysis functionality available from the API. Unfortunately, when building web applications with this functionality, we sometimes spend more time figuring out how to arrange the various HTML UI elements on the page than coding with the ArcGIS JavaScript API. Each application typically provides one or more UI elements in addition to the map for user interaction or displaying the results of some analysis. Since the ArcGIS JavaScript API includes all of the Dojo UI libraries, we can use the Dojo BorderContainer to easily lay out these elements in a standard way.
Each instance of the BorderContainer allows for up to 5 different regions: top, bottom, right, left, and center. Each region should contain a Dojo layout element. If a region needs to be broken down further, BorderContainers can be used as a region of a parent BorderContainer.
Each BorderContainer has two distinct ways to arrange its child elements and is controlled by the ‘design’ attribute whose value can be ‘headline’ or ‘sidebar’. When a BorderContainer uses a headline design, the top and bottom regions take precedence and stretch to 100% of the width. A sidebar design will stretch the right and left regions to 100% of the height. In the examples below we have two identical BorderContainers with 5 regions, but the only difference is the value of the ‘design’ attribute.
Headline:
Sidebar:
The location of each child element is specified with the ‘region’ attribute. It’s important to note that for the top and bottom regions you shouldn’t set the width, only set the height. For the right and left regions don’t set the height, only set the width. No width or height should be set for the center region as the BorderContainer will fill in the remaining space with this element.
Another UI consideration of the BorderContainer is the ‘gutters’ attribute which by default is ‘true’ and will add a 5px margin around all child elements. To view additional examples check out the nightly test pages related to the Dojo BorderContainer.
Here are a few other considerations that might be helpful:
-
Use CSS to make sure the html and body tags use the entire viewport.
html, body {
height: 100%;
width: 100%;
margin: 0;
padding: 0;
}
-
Set the Dojo theme and application background color in the body tag.
<body class="soria" style="background-color: steelblue; overflow: hidden;">
-
The first element inside the body tag should be a BorderContainer. You can use the style attribute to add an overall margin if desired.
<div dojotype="dijit.layout.BorderContainer" design="headline" gutters="false" style="width: 96%; height: 95%; margin: 2%; border:solid 3px silver;">
-
Use a Dojo ContentPane for the map div so it’s positioned correctly relative to the other UI elements. It also provides a ‘resize’ event for repositioning and resizing the map.
<div id="map" dojotype="dijit.layout.ContentPane" region="center" style="border:solid thin silver; overflow:hidden;"></div>
We’ve posted some example layouts in the Code Gallery or you can view them at this sample page. These show simple user interfaces built using the BorderContainer.
You can use thes samples as a starting place for your own work. Spending a little time up front understanding how the Dojo BorderContainer works will allow you to quickly start building web applications that use the ArcGIS JavaScript API.
Contributed by Sathya Prasad and John Grayson of the ESRI applications prototype team