Setting column sizes for Formatted Grids

There are two ways to set column sizes for the data shown in Formatted Grid components:

You can explicitly set column widths using the [ColumnWidth] tag in the data source. This applies to both spreadsheet-formatted grids and thematic grids.

OR
You can use the column width in the spreadsheet to determine the column sizing in the form. This only applies to spreadsheet-formatted grids.

Using the [ColumnWidth] tag

Using the [ColumnWidth] tag, you can set a specific size for each column in the Grid data source, using either pixels or percentages as the size units. This tag can be used with both thematic grids and spreadsheet-formatted grids.

To use the [ColumnWidth] tag:

Add the tag to the control column of the Grid data source. Typically, the tag is placed near the top of the data source, above any content rows (meaning rows marked with [Row] or [Fixed]).
If the grid is a spreadsheet-formatted grid, disable Fit Columns. If Fit Columns is enabled, then the [ColumnWidth] tag is ignored and instead the Fit Columns behavior applies (see the following section). This requirement does not apply to thematic grids as the Fit Columns option is always ignored for thematic grids.

Within the [ColumnWidth] row of the data source, enter a size for each content column that will be displayed in the form. This means any column that is flagged with [Column] or [Fixed]. Sizes can be entered as follows:

Size	Description	Examples
Specific size	Enter a single number to set the size of the column to that number. The size can be expressed in pixels or as percent.	50px 25%
Size range	Enter a minimum and maximum number to set the allowed size range for the column. The column will be sized somewhere in this range, depending on the other column sizes and the overall width of the component. Use a hyphen to separate the minimum and maximum number. The column will display at the minimum size by default. If the total of all column widths is less than the overall width of the component, then the column will "flex" wider, up to the maximum size. When mixing pixels and percents in a range, it is possible for the maximum number to end up smaller than the minimum number once the percent is resolved to pixels. In this case, the maximum number is effectively ignored and the column will not expand past its minimum number.	50px-100px 25%-40% 50px-25%
No size	If the column has no defined size, then the column will be sized as if it has a minimum size of 0px and an unlimited maximum size. Therefore its rendered size will depend on the other column sizes and the overall width of the component. The column will display at the minimum size by default. If the total of all column widths is less than the overall width of the component, then the column will "flex" wider, with no maximum size limit.	N/A

Size

Description

Examples

Specific size

Enter a single number to set the size of the column to that number. The size can be expressed in pixels or as percent.

50px

25%

Size range

Enter a minimum and maximum number to set the allowed size range for the column. The column will be sized somewhere in this range, depending on the other column sizes and the overall width of the component. Use a hyphen to separate the minimum and maximum number.

The column will display at the minimum size by default. If the total of all column widths is less than the overall width of the component, then the column will "flex" wider, up to the maximum size.

When mixing pixels and percents in a range, it is possible for the maximum number to end up smaller than the minimum number once the percent is resolved to pixels. In this case, the maximum number is effectively ignored and the column will not expand past its minimum number.

50px-100px

25%-40%

50px-25%

No size

If the column has no defined size, then the column will be sized as if it has a minimum size of 0px and an unlimited maximum size. Therefore its rendered size will depend on the other column sizes and the overall width of the component.

The column will display at the minimum size by default. If the total of all column widths is less than the overall width of the component, then the column will "flex" wider, with no maximum size limit.

N/A

NOTE: If units are not specified on the number (px or %), then pixels are assumed. It is recommended to place units on all numbers to avoid confusion and to prevent Excel from auto-converting certain entries into dates.

If you are using percentages, the column width is determined using the total rendered width of the Formatted Grid component. For example, if you specify 25% for a column and the component width is 400 pixels, then the column will be 100 pixels wide. The component width may be a fixed size (such as 400px) or a relative size (such as 50% of the form or of the parent panel). If the component width is relative, then when the form is rendered the actual component width is calculated first and then the column width is calculated.

If the total of all column widths (using the fixed or minimum size) exceeds the overall width of the component, then a horizontal scroll bar will be present on the grid. In this case, you must define a width for all columns because any columns without a defined width are sized using the 0px minimum and therefore will not be visible.

If the total of all column widths is less than the overall width of the component, then the columns will be sized as follows:

Any columns with a defined size range or with no defined size will be expanded wider. The excess width will be allocated among these "flex" columns evenly, except that no column with a defined range will exceed its defined maximum size. Any leftover width (for example, due to rounding) is given to the last column that has not exceeded its maximum size.
If all columns have a defined size or range, and after expanding to the maximum range there is still excess width, then that width will display as a gap between the right edge of the last column and the right edge of the grid component.

If all columns use percent sizes, then the following applies:

If the total of all column widths equals 100%, then the data source contents will exactly fit the component width.
If the total of all column widths is less than 100%, then a gap will display between the right edge of the last column and the right edge of the grid component.
If the total of all column widths is greater than 100%, then a horizontal scroll bar will be present on the grid.

It is possible to mix percents and pixels for different columns within the grid, and even within a single range. Each column will be sized according to the rules described above to determine the total column widths and therefore the overall grid display.

If the [ColumnWidth] tag is not present in the data source, then the grid is treated as follows, depending on the format type:

Thematic grid: The overall width of the grid is allocated equally to all columns. The column width in the spreadsheet is ignored.
Spreadsheet-formatted grid: The column width in the spreadsheet is used to determine the column sizing. See the following section for more information.

Using the column width in the spreadsheet

This option only applies to spreadsheet-formatted grids. Thematic grids do not use the column width in the spreadsheet.

To use the column width in the spreadsheet, remove the [ColumnWidth] tag from the data source (if it is present) and then size each column in the spreadsheet as desired. Columns will be sized as follows in the form, depending on whether the Fit Columns property is enabled in the component properties.

If Fit Columns is enabled, then the columns will be auto-scaled to fit the width of the Formatted Grid component on the form canvas. If the overall width of the columns is less than the component width, the columns will be scaled wider. If the overall width of the columns is greater than the component width, the columns will be scaled narrower. The scaling is proportional based on the width of the columns as defined in the spreadsheet.
If Fit Columns is disabled, then the columns will display in the grid based on their width in the spreadsheet. This is primarily intended for situations where the overall width of the columns exceeds the width of the component, and instead of shrinking column width you want the user to be able to scroll horizontally to see additional columns. Keep in mind the following:

NOTE: If the overall width of the columns is less than the width of the component, then the columns will still be scaled to fit the width of the component. However in this case, the "extra" width is allotted to all columns evenly instead of proportionally. In other words, the initial column width is set based on the width in the spreadsheet, and then the extra width is divided by the number of columns and added to each column.

By default, Fit Columns is enabled for all new Formatted Grid components.

Printing considerations

If you intend to allow users to print the form by generating a PDF, then the overall column width should not exceed the component width. In other words, all columns must be visible in order to be printed.

The easiest way to achieve this is to configure the grid so that the columns never scroll. However, you may have a situation where you want the grid to be scrollable online but fitted to the component width when generating a PDF. You can do this by dynamically changing the grid configuration for the PDF—for example, to dynamically enable Fit Columns for a spreadsheet-formatted grid. For more information, see Configuring an Axiom form for printing.

Get more information and training resources: www.kaufmanhall.com

Was this topic helpful?

formattedgrid_columnwidth.htm