com.smartgwt.client.docs

Interface FormLayout

public interface FormLayout

Form Layout

FormItem Placement in Columns and Rows

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 startRow, endRow, colSpan and 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 endRow to false on a ButtonItem in order to place a button in the same row as any other item.

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

DynamicForm.colWidths controls the widths of form columns. FormItems that have "*" for FormItem.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 DynamicForm.fixedColWidths.

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 "30%" and "70%" respectively, the percentage sized items will split up the available space after the fixed size items have been rendered.
Note that 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).

Managing Overflow

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:

1. Allow scrolling when necessary, using overflow:auto, either on the immediate form, or on some parent.
2. Place the form in a Layout along with a component that can render any specified size, such as a ListGrid. In this case, the Layout will automatically shrink the grid in order to accommodate the form.
3. Ensure that the form can always render at a designed minimum size by reducing the number of cases of variable-sized text, and testing remaining cases across all supported skins. For example, move help text into hovers on help icons, or clip long text values at a maximum length and provide a hover to see the rest.

Adaptive Layout

To have various automatic adjustments made to render your form items in a single column, you can use linearMode. Importantly, you can have this mode automatically applied to a form on handset devices by setting linearOnMobile true. For further details and the properties that are available to customize this mode, see the linearMode documentation.

Several examples of Form Layout are available @see here.

See Also:

FormItem.getWidth(), FormItem.getHeight(), DynamicForm.getItemLayout(), DynamicForm.getItemLayout(), DynamicForm.getLinearMode(), DynamicForm.getLinearOnMobile(), DynamicForm.getNumCols(), DynamicForm.getLinearNumCols(), DynamicForm.getFixedColWidths(), com.smartgwt.client.widgets.form.DynamicForm#getColWidths, DynamicForm.getMinColWidth(), DynamicForm.getCellPadding(), DynamicForm.getCellBorder(), DynamicForm.getSectionVisibilityMode(), FormItem.getWidth(), FormItem.getLinearWidth(), FormItem.getHeight(), FormItem.getStaticHeight(), FormItem.getTitleColSpan(), com.smartgwt.client.widgets.form.fields.FormItem#getColSpan, FormItem.getLinearColSpan(), FormItem.getRowSpan(), FormItem.getStartRow(), FormItem.getEndRow(), FormItem.getLinearStartRow(), FormItem.getLinearEndRow(), ButtonItem.getStartRow(), ButtonItem.getEndRow(), FormItem.getHeight(), TextAreaItem.getStaticHeight(), ShuttleItem.getWidth(), ShuttleItem.getHeight()