AX2141

Formatted Grid component for Axiom forms

Using the Formatted Grid component, you can display information in a grid format—such as reporting data, lists of information, or grid "worksheets" with various user inputs. The Formatted Grid component takes a designated section of the source spreadsheet and displays the contents of those cells in the Axiom form.

You can define formatting for the grid contents, such as font size and colors, background colors, text alignment, and borders. To apply formatting, you tag each row and column in the grid with style names. The formatting in the spreadsheet is ignored, with the exception of number formats.

Defining a formatted grid is a two-part process that requires the following:

Creation of a Grid data source in the spreadsheet to define the portion of the spreadsheet to display in the form, and to define the formatting of the grid contents.
Placement and configuration of a Formatted Grid component on the Axiom form canvas.

The Formatted Grid component can be used for data display only, or to support rich interactivity such as input cells, combo boxes, and more. Formatted grids are very flexible and support many different features. Each formatted grid can look and act very differently depending on the formatting applied and the features used. For more information, see the related topics such as:

The Formatted Grid component is one of several options that can be used to display reporting data in an Axiom form, along with the Fixed Report component and the Data Grid component. For more information on the differences between these components and when to use each, see Displaying reporting data in an Axiom form.

NOTES:

Older formatted grids may use formatting defined in the spreadsheet, instead of using row and column styles. These older grids are known as spreadsheet-formatted grids. The ability to use spreadsheet formatting is deprecated, and is only supported for backward-compatibility. Many newer features of formatted grids are not supported in spreadsheet-formatted grids. If you have existing spreadsheet-formatted grids and you need information on how to edit them, or if you want information on how to migrate them to the new grid style, see Using spreadsheet formatting with Formatted Grids (deprecated).
Formatted grids that use the default formatting method are also known as thematic grids, to differentiate them from the legacy spreadsheet-formatted grids.

Data source tags

A Formatted Grid component must have a defined data source within the file to indicate the data for the grid. The tags for the data source are as follows:

Primary tag

[Grid;DataSourceName]: The DataSourceName identifies this data source so that it can be assigned to a Formatted Grid component. (missing or bad snippet)
(missing or bad snippet)

Row tags

[Row]: Each row flagged with this tag (or the [Fixed] tag) defines a row of values to display in the grid.

[Fixed]

Optional. This tag can be used instead of the [Row] tag to flag a row as a non-scrolling header in the grid. Only the top row or rows in the grid can be fixed. If the [Fixed] tag is placed below a [Row] tag, the row will not be fixed and instead displays as a normal row.

The deprecated tag [Header] has the same effect. However, this legacy tag should not be used in new data sources.

If a [RowID] column is being used, fixed rows are not selectable.

[ColumnWidth]: Optional. Specifies a width for each column, in pixels or as a percent of the overall grid width. For more information, see Setting column sizes for Formatted Grids.

[PDFColumnWidth]: Optional. Specifies a width for each column, to be used when generating a PDF of the form. For more information, see Configuring a Formatted Grid component for printing to PDF.

[ColumnStyle]

Specifies the column style for each column, to determine the formatting applied to each column. For more information about applying styles grids, see Applying formatting to Formatted Grids.

The data source can have one or more [ColumnStyle] rows. The first [ColumnStyle] row should be placed at the top of the data source, before any content rows (meaning rows tagged with [Row] or [Fixed]). The specified column style at the top of the data source will apply to the contents in that column until another [ColumnStyle] row is found. The column style in that row will then be used until another [ColumnStyle] row is found, and so on.

[DrillDownColumns]: Optional. The presence of this tag enables data drilling for the grid, and this row is used to flag the columns to be included in the drill results. For more information on drilling tags, see Configuring the Grid data source for data drilling.

Column tags

[Column]

Each column flagged with this tag (or the [Fixed] tag) defines a column of values to display in the grid.

[Fixed]

Optional. This tag can be used instead of the [Column] tag to flag a column as a non-scrolling column in the grid. Only the leftmost column or columns can be fixed. If multiple columns are fixed, they must be continuous within the grid. If the [Fixed] tag is placed to the right of a [Column] tag, it will be ignored and treated as a normal grid column.

This tag is ignored if either of the following options are enabled in the component properties: Fit Columns, Extended Height. The columns will be treated as normal grid columns.

The deprecated tag [FixedColumn] has the same effect. However, this tag should not be used in new data sources.

[RowHeight]

Optional. Specifies a height for each row in pixels, or as a percent applied to the row style height. The row height is typically set by the row style, so this column is only intended for cases where you need to override the style or set the row to a height that is not supported by the available styles. For more information, see Setting row sizes for Formatted Grids.

[RowID]

Optional. Enables the ability to select rows in the grid. This column can contain any value that uniquely identifies each row in the grid, such as numbers or names. This is only necessary if you want to implement interactivity for the form based on the currently selected row of the grid. If you do not need this column, it can be omitted, and then users will be unable to select rows in the grid. For more information, see Selected row.

[RowStyle]

Specifies the row style for each row, to determine the formatting applied to each row. The row style applies to the entire row, except where it is overridden by a column style. For more information about applying styles to formatted grids, see Applying formatting to Formatted Grids.

[DrillDownRows]

Optional. When enabling data drilling for the grid, this column is used to flag the rows that are eligible for drilling. For more information on drilling tags, see Configuring the Grid data source for data drilling.

(missing or bad snippet)

The following example shows a Grid data source tagged in a sheet. In real implementations this data would most likely be generated by an Axiom query or another data query method; this example uses fixed sample data in order to show the placement of the tags to the data.

To use the Data Source Wizard to add the tags to a sheet, right-click in a cell and then select Create Axiom Form Data Source > Formatted Grid. You can also highlight a range of data first and then use the wizard to add the tags around that data. The cells in the row above and the column to the left of the selected area must be blank in order for Axiom to place the tags in sheet.

When the form is rendered, this example grid displays as follows:

Notice the difference between the formatting in the form versus the formatting (or lack thereof) in the spreadsheet. The formatting in the spreadsheet is ignored. The formatting in the form is determined by the styles applied to the rows and columns in the data source. For example, the subtotal rows use a style such as row,bold,brd-tb,brd-color-s6, to apply bold text and borders to the row.

If desired, you could format the data in the spreadsheet, and that formatting would be ignored when the form is rendered. For example, you might want to bold the header rows and put underlines on the subtotal rows, just so the data is easier to read in the spreadsheet when form designers are working in the file.

Component properties

You can define the following properties for a Formatted Grid component.

(missing or bad snippet)(missing or bad snippet)

Item	Description
Data Source	The data source for the grid. You must have defined the data source within the file using the appropriate tags in order to select it for the grid. (missing or bad snippet)
Data Source Load	(missing or bad snippet) NOTE: Asynchronous loading cannot be used with embedded forms. If the Formatted Grid component will be used inside an embedded form, it must use Inline loading.
Selected Row ID	The currently selected row in the grid. This setting is optional and should only be used if you want users to be able to select a row in the grid to impact the Axiom form in some way. The data source must have a `[RowID]` tag in order to use this feature. This setting serves two purposes: It defines the initially selected row in the grid, if you want the grid to start with a particular row selected. You can leave this blank to specify that no row is selected, or enter a row ID from the RowID column in the data source. When a user views the form and selects a row in the grid, the row ID of the user's selection is submitted back to the source file and placed in this cell on the Form Control Sheet. Formulas can reference this cell in order to dynamically change the form based on the currently selected row in the grid. For more information, see Selected row. NOTES: This setting supports indirect cell references. You can enter a cell reference in brackets, such as `[Info!B3]`. This causes the selected row ID to be read from and written to the specified cell reference instead of directly within the Selected Row ID cell. This setting supports use of the FormState tag and the SharedVariables tag, so that the selected row ID is stored in memory instead of written to the file, and therefore can be shared with other files. (missing or bad snippet)
Auto Submit	Specifies whether the Axiom form automatically updates when a user changes the state of the grid. By default this is enabled, which means that the form automatically updates in response to user activity such as: Changing the selected row (if using RowID) Editing an unlocked cell in the grid Interacting with a special formatted grid feature, such as a drop-down list or a check box If this setting is disabled, then edits made to the grid will not trigger an update. The changes will be submitted back to the source file when another component triggers an update, such as a Button component.
Use Lightweight Auto Submit	Specifies whether a special lightweight auto-submit behavior applies to input cells in the grid. If enabled, the following items are affected: simple unlocked cells and TextArea tags. (missing or bad snippet) When enabled, the following behavior applies: When a user edits an unlocked cell or a text box, only that new value is submitted back to the form source document on the server. The source document is calculated so that any formulas referencing the changed cell are updated. No data refresh occurs, just a calculation. If any of the following cell types in the grid have modified values after the calculation, the form web page is updated to display these new values: regular locked or unlocked cells, cells with Format tags, and cells with TextArea tags. No other form values are submitted, and no other form components are updated. The regular form update process does not occur. This option can be enabled by itself or in conjunction with Auto Submit. This option overrides auto-submit behavior for the affected cells, but all other cells can continue to use the regular auto-submit behavior or not as desired.
Save On Submit	(missing or bad snippet)
Title Text	The title text for the component. This text displays in the title bar for the component within the Axiom form, if the title bar is enabled. If the title bar is disabled, then this text does not display at all in the form. It is assumed that if you are not using the title bar, then you have defined title text in the grid itself. (missing or bad snippet)
Show Title Bar	(missing or bad snippet)
Collapse Height	(missing or bad snippet)
Extended Height	Specifies whether the height of the grid should extend to show all rows of the data source. By default this is disabled. If the rows included in the data source exceed the height of the grid component on the form canvas, then a vertical scroll bar will be present on the grid, allowing users to scroll to view all rows. If this option is enabled, then the height of the grid will automatically extend downward to include all rows. If the rows exceed the size of the form window, then the user can scroll the window to view all rows. For more information on the impact of using extended height, see Setting row sizes for Formatted Grids. This option is primarily intended for use when printing to PDF. If you define any PDF Settings, then it is automatically applied along with those settings. For more information, see Configuring a Formatted Grid component for printing to PDF.
PDF Settings	Defines settings to apply to the grid when generating a PDF of the form. Click the [...] button to open the PDF Settings dialog and complete the settings. You can define the number of rows to show per page and configure header rows to repeat. For more information on these settings, see Configuring a Formatted Grid component for printing to PDF.
Grid Formatting	Specifies how the contents of the grid are formatted. By default, this is set to Thematic and should not be changed. Thematic formatting refers to the use of row and column styles to format the grid. Older, existing grids may be set to Spreadsheet, which refers to the deprecated approach of using formatting defined in the spreadsheet. If you have an old spreadsheet-formatted grid, keep in mind that many grid features are not supported in this deprecated format. For more information, see Using spreadsheet formatting with Formatted Grids (deprecated). IMPORTANT: This setting is only present on the Form Control Sheet. Generally speaking, the only reason to edit this property is if you are migrating an old spreadsheet-formatted grid to use thematic formatting. Newly created grids should not use spreadsheet formatting, unless you are working in an older system that has not yet migrated to the new approach, and you need to maintain backward-compatibility.

(missing or bad snippet)(missing or bad snippet)

For Formatted Grid components, the grid-level style only impacts the external grid container; it does not affect the internal grid contents. Row and column styles should be applied to the Grid data source to define the formatting for the grid contents. For more information, see Using row and column styles with Formatted Grids.

(missing or bad snippet)(missing or bad snippet)

Using the Data Source Assistant with a Grid data source

You can use the Data Source Assistant to:

Add column and row tags to the data source. For general information on using the Data Source Assistant to add column and row tags, see Using the Data Source Assistant.
Apply styles to rows and columns. For information on using the Data Source Assistant to apply styles, see Using row and column styles with Formatted Grids.
Edit content tags. For information on using the Data Source assistant to work with content tags, see Creating and editing content tags in Formatted Grids.

The Selection Editor section of the Data Source Assistant is blank if you have your cursor in any of the following areas:

In the [ColumnWidth] row or the [RowHeight] column.
In the [RowID] row.
In a cell that contains a formula, or plain text or numbers.

You must populate these areas manually as needed.