WPanel GridLayout
GridLayout is used to arrange content in a WPanel into a grid. The number of rows and/or columns in the grid is specified and each WComponent added to the GridLayout occupies one cell in the grid. The width of cells in the grid is determined by the number of columns in the grid and each cell will have the same width.
NOTE, though, that GridLayout was originally designed as an emulation of a Java AWT or Swing GridLayout without any attempt to normalise the row height (though this can be done within a consuming application on a case by case basis). It is important that one does not confuse WPanel's GridLayout with a generic layout grid system like 960gs and its more modern offshoots. If we were able to design this from scratch rather than inheriting an 11 year-old Swing-like API we would not have this layout.
GridLayout is considered a legacy layout and should be avoided in modern applications; especially those which need to be responsive to small screens.
- Diagram information
- Calculating the grid
- Layout configuration
- Empty Cells
- HTML output
- Related Components
- Further information
In the diagrams illustrating the various settings for GridLayout the GridLayout content is comprised of WPanels each of which has a border; this is done to provide easy recognition of the cell boundaries.
The number of columns or the number of rows may be individually specified or specified together but at least one of these must be specified. If the number of columns is specified then this is used to determine the columns in the grid. If the number of columns is not specified it is calculated by dividing the number of cells by the specified number of rows.
The width of grid cells is determined by the number of columns in the grid. If, however, a hgap is specified then the first and last cells in each row in the grid will be half of this hgap wider than the other cells in the grid. This is done to minimise the variation between the width of the cells at the extremities of the grid and those within the grid.
The grid is divided into rows and columns but each column is the same width (see Wpanel ColumnLayout if you need columns with different width and alignment).
When there are 12 or fewer columns in the grid the column width is set using a class attribute value on the GridLayout root element (normally a div). If there are 6 columns in the grid, for example, the GridLayout's div root will have a class attribute which includes wc-gridlayout-col-6.
When there are more than 12 columns in the grid the column width is set using inline-styling on each cell. This obviously makes for far more HTML sent to the client and for more difficulty in producing sensible or easily manipulated rules for responsive grids.
GridLayout is a rigid predetermined content layout mechanism, therefore it has few options for styling. Only the space between rows of cells and cells within a row is available for manipulation. The content of all cells in the grid is vertically aligned to the top of the row of cells. Each cell in the grid is left aligned by default.
GridLayout supports two properties which are used to put space between cells and rows of cells. These are outlined in horizontal spacing for space between cells and [vertical spacing] for space between rows of cells. To put space around a GridLayout use its containing WPanel Margin.
The default for any GridLayout is to not apply any space between cells or rows of cells. Any required space must be specified in the UI specification.
The hgap property specifies the horizontal space between cells in a row. Half of the hgap is applied as each of left and right of each cell except the first and last. For the first cell in a row half of the hgap is applied only to the right. For the last cell in a row half of the hgap is applied only to the left. This makes the first and last cells slightly wider (half of the hgap) than the other cells. This makes a smaller difference than any alternative which would result in one cell being a whole hgap wider than the other cells leading to greater visual disparity.
From WComponents 1.1.4 onwards the hgap will be applied as described in Theme intra component spacing. The hgap class values are applied to the GridLayout root div. In WComponents 1.1.3 and before the hgap was applied as a number of pixels (half the requested hgap each) as inline CSS on every cell in the grid.
This change was made as part of addressing Issue #571 since by moving the hgap from inline CSS to a small set of class attribute values the gaps may be more easily manipulated at the application level. The use of a small set of classes also improves UI consistency and application of a standard style to a suite of applications.
The vgap property specifies the space between rows of cells in a GridLayout. The vgap is applied as a margin to the top of each row of cells excluding the first.
From WComponents 1.1.4 onwards the vgap will be applied as described in Theme intra component spacing. The vgap class values are applied to the GridLayout root div. In WComponents 1.1.3 and before the vgap was applied as a number of pixels as inline CSS on each row in the grid other than the first.
This change was made as part of addressing Issue #571 since by moving the vgap from inline CSS to a small set of class attribute values the gaps may be more easily manipulated at the application level. The use of a small set of classes also improves UI consistency and application of a standard style to a suite of applications.
A GridLayout may contain empty cells. These cells are produced when a WComponent is added to a GridLayout 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 cell will be output to the UI and will have the appropriate width, hgap and vgap (if any) but will be empty. This is done to maintain the requested grid formation. The addition of such components to a GridLayout may result in unexpected or erroneous rendering.
GridLayout is always a child of WPanel and so will exist within the root element of that component. The root of a GridLayout is a div element. This wrapper div will not have an id attribute but will have the class attribute with value wc-gridlayout.
When the number of columns in the grid is no more than 12 the wrapper div will also have a class attribute value indicating the number of columns:
-
wc-gridlayout-col-1for 1 column -
wc-gridlayout-col-2for 2 columns -
wc-gridlayout-col-3for 3 columns -
wc-gridlayout-col-4for 4 columns -
wc-gridlayout-col-5for 5 columns -
wc-gridlayout-col-6for 6 columns -
wc-gridlayout-col-7for 7 columns -
wc-gridlayout-col-8for 8 columns -
wc-gridlayout-col-9for 9 columns -
wc-gridlayout-col-10for 10 columns -
wc-gridlayout-col-11for 11 columns -
wc-gridlayout-col-12for 12 columns
When the Grid has more than 12 columns the wrapper div does not have a class value indicating the number of columns. Instead each cell will have its width set as an inline style.
When the GridLayout has a vgap the wrapper div will have a class value indicating the expected gap type as described in Theme intra component spacing.
When there are more than one column in the layout (which should be always) then the grid will consist of rows and columns.
Each row in the grid is a div element. When the GridLayout has a hgap each row's div will have a class value indicating the expected gap type as described in Theme intra component spacing. When there is exactly one column in the GridLayout (use a different layout) then there will not be any row wrapper divs.
Each cell in the grid is a div element. This element will not have an id but will have a class value wc-cell. If the grid has more than 12 columns then the div output by each cell in the grid will have inline CSS to set its width.
The following is typical output for a GridLayout. In this example the grid has 3 columns, a small hgap and a medium vgap.
<div class='wc-gridlayout wc-gridlayout-col-3 wc-vgap-med'>
<div class='wc_gl_row wc-hgap-sm'>
<div class='wc-cell'>
<!-- CONTENT HERE -->
</div>
<div class='wc-cell'>
<!-- CONTENT HERE -->
</div>
<div class='wc-cell'>
<!-- CONTENT HERE -->
</div>
</div>
<!-- ... repeat for each row -->
</div>[vertical spacing]: #vertical spacing