WPanel ColumnLayout
ColumnLayout is used to arrange content in a WPanel into a set of columns. The number, relative size and alignment of the columns is determined within the application but cannot be changed after the layout is set. Each WComponent added to a ColumnLayout will create a column. If the number of WComponents added to the layout exceeds the number of columns in the ColumnLayout then a new row of columns will be created.
If a UI design requires mutable columns then WRow and WColumn must be used.
- Diagram information
- Using ColumnLayout
- Layout configuration
- Empty Cells
- Responsive design
- Related Components
- Further information
In the diagrams illustrating the various settings for ColumnLayout the ColumnLayout content is WPanels each of which has a border (Type.BOX); this is done to provide easy recognition of the column boundaries.
Columns are an instrinsic structural component for many web UIs and are generally mere containers for other content. Therefore there are few styling options available in ColumnLayout. The relative width of columns, and the alignment of elements within a column can be specified, as can the space between rows and columns.
The content of all columns is vertically aligned to the top of the column.
ColumnLayout supports two properties which are used to put space between columns and rows. These are outlined in the hgap property for space between columns and the vgap property for space between rows. To provide spacing around the ColumnLayout its containing WPanel may have a Margin. The default for any ColumnLayout is to not apply any space between columns. Any required space must be specified in the UI specification.
The hgap property specifies the space between columns. Half of the hgap is applied to the left and right of each column except the first and last. For the first column in a row half of the hgap is applied only to the right. For the last column in a row half of the hgap is applied only to the left. This makes the first and last columns slightly wider (half of the hgap) than the other columns (if the column widths are all equal). This makes a smaller difference than any alternative which would result in one column being a whole hgap wider than the other columns leading to greater visual disparity.
If hgap is not set within the application the columns will abut each other unless custom CSS is used to separate them. See Theme intra component spacing for details of how gaps are applied.
The vgap property specifies the space between rows in a ColumnLayout and has effect only if the number of components added to the ColumnLayout is greater than the specified number of columns. The vgap is applied to the top of each row of columns except the first.
If vgap is not set within the application the rows will abut each other unless custom CSS is used to separate them. See Theme intra component spacing for details of how gaps are applied.
Each column may be aligned independently. The alignment determines how the components added to the ColumnLayout will be presented in the UI.
Available settings for this property are:
-
LEFT(default) in which components in a column are left aligned relative to the column; -
RIGHTin which components in a column are right aligned relative to the column; -
CENTERin which components in a column are center aligned relative to the column.
Column width is indicated as a positive Integer and is translated as a percentage of the available width (the width of the notional content box of the parent container).
If the total width of all columns in a columnLayout is greater than 100 then all columns from the one which sends the width over 100% will wrap. This is considered an error state.
There is no default for column width. The percentage width of all columns in a ColumnLayout must be explicitly specified in the UI specification. If a hgap is used to separate columns then the actual width of the columns will be slightly smaller than the specified width.
The width is translated as a percentage to cope with the many variables which determine the user's viewport size. This makes columns a better structural layout element than would be the case if absolute widths were used and a more rigid structural layout than FlowLayout.
Column width for any or all columns may be set to 0 when creating a ColumnLayout. This will then not set a specific width for that column. One would use this in conjunction with a htmlClass set on the containing WPanel and custom CSS to set the column widths. This is particularly useful for creating responsive UIs.
An outer layout for an application may require three columns in a ColumnLayout but we want granular control over when columns collapse.
// Set up a 3 column ColumnLayout with 'undefined' column widths.
WPanel panel = new WPanel();
panel.setHtmlClass("outer-columns");
panel.setLayout(new ColumnLayout(new int[]{0, 0, 0}));One could then use CSS such as the following to style the columns (so much easier to write in Sass!).
.outer-columns > .wc-columnlayout > .wc-row > .wc-column {
width: 20%
}
.outer-columns > .wc-columnlayout > .wc-row > .wc-column:first-child {
width: 50%
}
.outer-columns > .wc-columnlayout > .wc-row > .wc-column:last-child {
width: 30%
}
.outer-columns > .wc-columnlayout > .wc-row + .wc-row {
margin-top: 0.5em
}
@media only screen and (max-width: 1000px) {
.outer-columns > .wc-columnlayout > .wc-row > .wc-column {
display: block;
width: 100%;
text-align: left;
}
.outer-columns > .wc-columnlayout > .wc-row > .wc-column + .wc-column {
margin-top: 0.25em;
}
}A ColumnLayout may contain empty cells. These cells are produced when a WComponent is added to a ColumnLayout but that WComponent has no output into the XML. This may be because the WComponent has no UI consequence or because it is not yet available to the UI.
In this case the column produced by the cell will exist in the UI and will have the appropriate width, hgap and vgap (if any) for that column. It will, however, be empty. This may lead to unexpected or erroneous layouts.
ColumnLayout is used to create a row with columns. This may result in sub-optimal rendering on small screens. There are two ways to overcome this.
For simple scenarios the inbuilt responsive design opt-in may be used. In this case all columns will become individual rows and will fill the viewport if the view becomes less than a given size (determined to be the exposed pixel width of a large mobile phone). To invoke this use the addHtmlClass(HtmlClassProperties) method:
// given WPanel panel
panel.addHtmlClass(HtmlClassProperties.RESPOND);Customising the responsive design for one's particular interface will almost always give best results. This can be achieved by writing custom CSS and giving the WPanel a custom HTML class name value or fixed id. For more information see Adding custom CSS and Theme class name conventions.