public interface FormLayout
With the default tabular layout mechanism,
items are laid out in rows from left to right until the number of columns, specified by
form.numCols, is filled, then a new
row is begun. Flags on FormItems, including
rowSpan, control row and column
placement and spanning.
Note that the most common form items (TextItem, SelectItem, etc)
take up two columns by default: one for the form control itself, and one for it's title.
The default setting of
form.numCols:2 will result in one TextItem or SelectItem per row.
Note also that
ButtonItems have both startRow:true and endRow:true by default. You must set startRow and/or
false on a ButtonItem in order to place a button in the same row as any
The log category "tablePlacement" can be enabled from the Developer Console to
watch items being placed. You can also set
form.cellBorder:1 to reveal the
table structure for layout troubleshooting purposes.
Row and Column Sizing
colWidths controls the widths
of form columns. FormItems that have "*" for
width will fill the column.
FormItems with a numeric width will have that width in pixels regardless of the column's
specified width, which may cause the column to overflow as described under
For row heights, the largest pixel height specified on any item in the row is taken as a minimum size for the row. Then, any rows that have "*" or "%" height items will share any height not taken up by fixed-sized items.
Individual item heights are controlled by
item.height. This may be specified
as an integer (pixel value), or a percentage string, or the special string "*", which
indicates an item should fill the available space.
Percentages allow developers to determine how the available space in the form is split amongst items. For example if a form has 4 items in a single column, 2 of which have an absolute pixel height specified, and 2 of which are have heights of
"70%" respectively, the percentage
sized items will split up the available space after the fixed size items have been
item.cellHeight may be specified to explicitly control the height of an item's cell. In this
case the specified
item.height will govern the size of the item within the cell (and if set to a percentage, this
will be interpreted as a percentage of the cellHeight).
Forms often contain labels, data values, or instructional text which can vary in size based on the skin, data values, or internationalization settings. There are a few ways to deal with a form potentially varying in size:
overflow:auto, either on the immediate form, or on some parent.
ListGrid. In this case, the Layout will automatically shrink the grid in order to accommodate the form.