Table of Contents
1. Defining Layouts
1.1. The Layout Grid
1.1.1. Overview
The layout grid divides the browser window up into rows and columns which determine how to react when the window is resized. The layout grid is specified in the <grid> element of the layout document. Within the <grid> you specify the rows and columns that make up your grid and how the available browser window real-estate should be divided up.
<layout>
<grid>
<cols>
<col width="50%" />
<col width="450px" />
<col width="50%" />
</cols>
<rows>
<row height="var" minheight="10px" />
<row height="var" minheight="100px" />
</rows>
<grid>
...
</layout>
Column sizes may be specified as one of the following:
If you've ever used framesets, then these types of size specifications will look familiar.
Bamboo (currently) supports one row size type:
In the future, Bamboo will offer more row and column size specification types.
1.1.2. Fixed Width Columns
Fixed width columns are specified by giving a measurement in pixels for the size attribute of a <col> element. For example:
<layout>
<grid>
...
<cols>
<col width="50px" />
</cols>
<grid>
...
</layout>
1.1.3. Relative Width Columns
Relative width columns allow you to allocate a portion of the space that is left over after all the fixed width columns are taken into account. Relative width columns are defined as a whole percentage such as 25%. Fractional percentages such as 25.23% aren't accepted.
The following example shows a layout with a 450 pixel fixed width column, and 20% relative width column. If the width of the browser window was 800 pixels, this would leave 350 pixels to be allocated to relative width columns. The relative width column would be resized to 20% of 350, or 70 pixels.
<layout>
<grid>
...
<cols>
<col width="20%" />
<col width="450px" />
</cols>
<grid>
...
</layout>
Note that the total of all percentages allocated to relative width columns must be less than or equal to 100%.
Relative width columns have a minimum width which is specified in pixels using the minwidth attribute of the <row> element. If no minwidth is supplied, Bamboo uses a default minwidth of 1px. As the browser window is resized downwards in width, Bamboo will make sure that the column's width is at least it's minimum width.
In the following example we give our relative width column from before a minimum width of 100 pixels. Now with a browser width of 800 pixels, the calculated width of our column is 70 pixels, as before, but because as this is lower than the minimum width, the minimum width is used instead, and so the columns width is set to 100 pixels.
<layout>
<grid>
...
<cols>
<col width="20%" minwidth="100px" />
<col width="450px" />
</cols>
<grid>
...
</layout>
1.1.4. Remainder Width Columns
Remainder width columns can be used to take up whatever space is left over after all fixed width and relative width columns are resolved. You can only have one remainder width column in a layout. If you declare more than one remainder width column, Bamboo will reject your layout.
In the following example, we add a remainder width column to our previous layout. As we saw above, when the browser window's width is 800 pixels, our relative width column resolves to 100 pixels. That with our fixed width column of 450 pixels gives us 550 pixels of used space, leaving a remainder of 250 pixels to be allocated to the remainder width column.
<layout>
<grid>
...
<cols>
<col width="20%" minwidth="100px" />
<col width="450px" />
<col width="*" />
</cols>
<grid>
...
</layout>
Note: in this example our last column has been declared as remainder width, but Bamboo allows any column to be the remainder width column.
As with relative width columns, remainder width columns have a minimum width attribute which determines the smallest width that they will be resized to when the browser window is resized down.
Assigning a minimum width of 300 pixels to our remainder width column means that instead of taking a width of 250 pixels which is the remainder from an 800 pixel wide window, it will use it's minimum width of 300 pixels. This means the total allocated column width will be 100 + 450 + 300, or 850 pixels. As this is wider than the browser window, horizontal scrolling of the layout will occur.
<layout>
<grid>
...
<cols>
<col width="20%" minwidth="100px" />
<col width="450px" />
<col width="*" minwidth="300px" />
</cols>
<grid>
...
</layout>
1.1.5. Variable Height Rows
Variable height rows can resize to accomodate the regions allocated to them. If only fixed height regions are allocated to a row, then that row will never extend beyond it's minimum height.
To specify that a row should be variable height, set it's height attribute to "var".
<layout>
<grid>
<rows>
<row height="var" />
</rows>
...
<grid>
...
</layout>
Variable height rows have a minimum height attribute that specifies the smallest height that they can take on. This is specified in pixels, and defaults to 1px if no value is supplied.
<layout>
<grid>
<rows>
<row height="var" minheight="100px" />
</rows>
...
<grid>
...
</layout>
1.2. Region Assignment
1.2.1. Overview
Regions in Bamboo are just <div> tags that you add to your HTML pages. Bamboo resizes them based on your layout grid and how you assign regions to cells in the layout grid.
Note that Bamboo doesn't create the <div> tags for you. You need to add those to your HTML page yourself. Bamboo just looks after positioning and resizing those <div>'s. If you declare a region mapping but don't create the corresponding <div> Bamboo will present an error message.
Bamboo also doesn't apply any formatting to your <div>'s, and doesn't alter the z-order, so you have control over these items as your do with any other HTML page.
1.2.2. Assigning A Region
Regions are declared to Bamboo using the <region> tag, with which you specify the ID of the region, and the start and end cells to which you want that region to be assigned. The start and end cells are specified by their row and column numbers.
In the following layout fragment, we have declared that the "navbar" region should be mapped to cover the cells from row 3, column 2 to row 3, column 4.
<layout>
<grid>
...
<grid>
<regions>
<region id="navbar" start="3,2" end="3,4"
fixedHeight="true" />
</regions>
</layout>
2. Connecting Bamboo Layouts To Your Site
2.1. Overview
There are several options available for using Bamboo layouts in your site. These options all achieve the same end-goal of linking the onresize JavaScript generated by Bamboo into your page, but they use different mechansims to do that. You should select the mechanism that best suits your environment.
| Option | Description | Best For |
|---|---|---|
| Layout WebService | A service hosted in the Bamboo website that you can call from your web site to process your *.layout files into layout JavaScript code. To use this service, your *.layout files must be publicly accessible via the web. | For those wanting to use Bamboo in a site on the public web, without downloading or installing any software. This is the easiest way to use Bamboo layouts in your site. More... |
| Webapp Bindings | A J2EE Servlet and tag library that can be plugged into a web-application to transparently apply Bamboo layouts to pages. | For those deploying an application into a servlet container this is the recommended option, as it provides the most transparent integration. More... |
| Offline Transformer | A small Windows / Linux / Mac OS X command that you can use to turn your *.layout files into static layout JavaScript that can then be linked into your HTML pages. | For those using Bamboo layouts with non-Java servers, or in static web-sites. More... |
| Ant Task | A custom task for Apache Ant that converts *.layout files into layout JavaScript. | For those who are already using Ant to build / package a web site. More... |
2.2. Layout Web Service
To use the LayoutWebService, your *.layout file must be on a publicly accessible website so that the service can retrieve it. This means it's a great option for public websites because you don't have to install any software on your own workstations or servers, but it can't be used on private sites such as intranets which are not accessible from the public network.
To get Bamboo to render your layout to JavaScript, you need to call the webservice, supplying it with the absolute URL of your *.layout file. This call is embedded in a <script> tag. For example:
<script language="javascript"
src="http://www.x1seven.com/projekts/bamboo/layoutservice?
url=http://www.mysite.com/main.layout"></script>
The LayoutWebService is actually part of the Webapp Bindings. This means that if you want to, you can set up your own central layout service to serve your sites.
2.3. Webapp Bindings
To use the Webapp Bindings in your webapp, you need to add the following JAR's from the Bamboo distribution to your webapp's WEB-INF/lib directory.
- x17_sft_curium_core_@meta.projekt.version.full.underscored@.jar
- x17_sft_curium_webapp_bindings_@meta.projekt.version.full.underscored@.jar
- log4j-1.2.11.jar
Edit your WEB-INF/web.xml file to include the following <servlet>, and <servlet-mapping> elements:
<servlet> <servlet-name>LayoutServlet</servlet-name> <servlet-class>com.x1seven.curium.layoutservlet.LayoutServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>LayoutServlet</servlet-name> <url-pattern>*.layout</url-pattern> </servlet-mapping>
You can then apply layouts using a <script> tag or the <bm:applylayout> tag. For example:
<script language="javascript" src="layouts/main.layout"></script> <bm:applylayout layout="layouts/main.layout" />
2.4. Offline Transformer
The OfflineTransformer will be added to Bamboo in the near future.
2.5. Ant Task
The AntTask will be added to Bamboo in the near future.
