Table of Contents
Overview
An output grid is a control that allows the user to view a range of items corresponding to a Table Named Range (TNR) from the spreadsheet model. These controls must be bound to a Table Named Range (TNR) (i.e. a two-dimensional range, including a width and height larger than 1 cell) and will contain an amount of rows and columns equivalent to the target range.
Properties
The properties of an output grid are outlined below. Please note that output grids are limited to 10,000 cells by default to prevent any performance issues. If your table named ranges contain more than 10,000 cells (i.e. a grid with 10 columns and 1000 rows) you will get an error. This limit can be changed in server and private cloud licenses.
Table Named Range
A list of all Table Named Ranges (TNR) defined in your spreadsheet model (i.e. a two-dimensional range, including a width and height larger than 1 cell).
Upon selecting a target named range, a process will begin to generate all of the metadata for the cells contained within this named range. Once this process has completed, a list of detected columns will be present below, including a Confirm button to validate the existence of each detected column.
Users should confirm the existence of the columns and then subsequently Submit the control in order to save and update the column properties for subsequent edit.
Note: To mitigate detrimental performance side effects, the maximum allowable cells within a target range is configurable by the system administrator in the Configuration Settings section of the Designer. By default, the maximum cells allowed in a given Table Named Range is 1000.
As a result, users attempting to generate grid controls using named ranges exceeding this value will not be able to generate columns for these controls, preventing submission. To exceed the maximum target cell count, please reach out to your system administrator.
Has Header
Select this feature if the selected named range contains headers in its first row.
This has an important effect upon calculations and can also aid in the auto-generation of columns for this grid control, so ensure that this value is updated appropriately
Hide Header
Enable this feature if you’d like to hide the column headers in the first row.
Responsive
This feature will determine whether or not to collapse columns that exceed the width of the viewable screen under the record's row.
This is advised for output grids, as it can aid in displaying information to end users that are accessing the application from mobile devices.
This is not advised for input grids, as it can cause undesirable column resizing and recalculation.
Enable Super Headers
This property allows adding multiple lines of headers with various widths above an Output Grid. When this option is enabled, you can select another Table Named Range from which the system can automatically pull the higher-level headers information.This feature allows for a multi-level approach to table headers, and allow you to combine multiple columns into groups of higher-level headers. Note that the column span of the Super Headers Named Range field must match that of the Output Grid Table Named Range.
Super Headers don't support any type of sorting, searching, or other features available in table headers. When Super Headers are enabled, these features are handled only by the lower-level headers as set by the Table Named Range for the Output Grid. The alignment of any headers created with Super Headers will use the same settings defined by the Header Alignment property in that grid.
The Super Headers Named Range field should only include the higher-level headers above the Table Named Range, and exclude the first level headers of each column.
Pagination
Enable this feature to allow for pagination on your grid. All functions will work appropriately across pages, such as sorting and searching.
This is particularly useful for large grids that often cause significant performance detriments in the user interface due to grid rendering.
Only default pagination options are currently available, but future releases will enable more user control over these features.
Use Metadata Formatting
This option configures the grid to handle data formatting per-cell rather than per-column, which allows each cell of a table utilize a different value format.
The information for these cells will be pulled from the target Table Named Range (TNR), based on the information found within the Excel model. For example, a cell that has a Date type with formatting MM/dd/yyyy will automatically become a calendar-based input and will display the associated date in the target format.
Note that data entry will still comply with the pre-existing formats (as if you were to have set the column to Date). Thus, the input mask (while entering the input’s value) may differ from the output format (the value that is displayed once the user has submitted or modified the value).
This feature may not be available for very large tables – this is dependent upon the size of the Table Named Range (TNR) and your server configuration. If the table's cell count exceeds configuration setting (called MaximumCellCount, defaulted to 1000), then the server does not generate a full set of the required metadata for these ranges. Thus, the Use Metadata Formatting feature cannot be utilized in these cases.
If you want to use the Use Metadata Formatting feature for large tables, then you may want to consider increasing the MaximumCellCount configuration setting to an appropriate value. For example, if the Table Named Range (TNR) represents a table having 10 columns and 200 rows, then the MaximumCellCount should be set to at least 2000 (10 x 200).
Disabled
The default mode (when this feature is disabled, or Use Metadata Formatting is unchecked) allows the user to set a Mask Type for each column separately. In this case, all cells in that column will use the same value formatting. For example, all data in the column are displayed either as percentages, dates, currencies, etc. For more information, see the Mask Type section on the Output Grid Column help page.
Enabled
Once you have enabled the feature (Use Metadata Formatting option is checked), each cell will be able to receive its own data formatting. This feature is called metadata formatting because it is based on the metadata information that is primarily collected from the provided spreadsheet model.
In this mode, the output grid table will allow each cell to use the same format that is set in the spreadsheet file, meaning that the values in each cell will be displayed in the same way as they appear in Excel.
Moreover, these formats can also be overridden in the Metadata Editor (Names) when required. For example, if you want to modify a cell's format from decimal to integer but prefer to leave the cell's format in the spreadsheet file as-is, you can simply set the new format for that cell in the Metadata Editor.
Also note that – in this mode – the column Mask Type options are not available, since the grid will be formatted on a cell-by-cell basis, rather than column-by-column.
Header Alignment
This feature will determine the alignment of all text within the header row of the grid.
Content Alignment
This feature will determine the alignment of all non-header text within the body of the grid.
Visible
Indicates whether the output grid control is visible.
This can be configured as Always or Never to indicate whether the output grid is statically visible or not.
Alternatively, if any Boolean Single Named Ranges (SNR) exist (i.e. ranges pointing to a single cell that evaluates to TRUE or FALSE), then the visibility of the output grid can be configured to reflect the value of that named range using the 'By Value Of' setting.
Regenerating Columns
When the width of a Table Named Range (TNR) has been modified, it is important to perform the Regenerate Columns action in order to reconfigure the columns within the grid control.
Without performing this action, the values sent to the calculation model may not be represented in the appropriate location.
Jean has a table named range in her workbook:
Name Age HasPets George 26 TRUE Jim 42 TRUE Sam 45 FALSE In a new iteration of her workbook, she adds an additional column called PetCount in order to quantify the number of pets that each individual has. She inserts the column after HasPets and uploads the new model to the Designer:
Name Age HasPets PetCount George 26 TRUE 2 Jim 42 TRUE 3 Sam 45 FALSE 0 Now, Jean needs to Regenerate Columns on her grid; otherwise, the new column for PetCount will not be visible from the user interface.
If you try to publish an application with a grid that has a column count that does not match the column count of the underlying named range, then you will be presented with a validation message that prompts you to regenerate columns for the target table.
Editing Column Properties
Below the Regenerate Columns button is a set of buttons, each representing a single column from the grid. Clicking the button corresponding to a column will allow editing the column's properties.
Changing the Column Order
To change the order of the grid columns, drag the (≡) buttons next to a given column to the desired position.
Actions
This section includes a series of buttons that are useful for applying changes to your control.
Reset Column Widths
Clicking this button will reset the grid's column widths to their default values (i.e. column widths will be automatically adjusted according to their contents).
Distribute Column Widths
Clicking this button will set the column widths of all active columns to Percentage and will evenly distributed the values (i.e. all columns will have the same width). For example, a grid with four columns will have each column set to 25% of the total width.
Grid Helper Classes
You can use the class names below to change the formatting of output grids.
- output-grid-header-{PageId}-{ControlId} Added to the "<thead>" tag of output grid
- output-grid-header-row-{PageId}-{ControlId} Added to each child "<tr>" tag of the "<thead>" tag
- output-grid-table-body-{PageId}-{ControlId} Added to the "<tbody>" tag of output grid
- output-grid-table-row-{PageId}-{ControlId}-{RowIndex} Added to each child "<tr>" element of the "<tbody>" tag
- output-grid-table-cell-column-{PageId}-{ControlId}-{RowIndex}-{ColumnIndex} Added to each child "<td>" element of the "<tr>" tag
For example, to change the color of the header, and 8th column of output grid, go to
Designer Home Page / StyleSheets / Add Style Sheet and add the text below text into the stylesheet editor
This will change the header color of the output grid to orange, and the header background will be red. The background of the 8th column will be blue.
Copy support
The output grid control includes support for copying.
Copy (CTRL+C)
If you want to copy contents into your clipboard, you will first need to make a selection. Output grid controls allow you to select either a rectangular cell range (Cell Selection) or multiple columns (Column Selection).
-
Cell Selection
You may select a range of cells by using the SHIFT key and clicking two cells. This will define the diagonal dimension of the rectangular range. This behaves similarly to selecting a cell range within Excel.
For example, hold the SHIFT key and click a starting cell which will indicate the beginning of a rectangular selection. Subsequently, holding SHIFT and clicking on another cell will mark the diagonal corner of the desired rectangular cell selection. In this sense, the start and end cell selection define the top-left and bottom-right corners of a rectangular range and all cells belonging to the rectangle will become selected. Each consecutive SHIFT and click of any cell will redefine the rectangular selection to include the new cell as the end cell, retaining the original starting cell.
Note that if you do not hold the SHIFT key while clicking a cell, it will instead activate Edit mode for that cell (rather than Select mode). When a cell is already in edit mode, holding SHIFT and clicking on another cell will turn the original cell into the start cell of a new selection, with the end cell being the clicked cell. This way, you do not need to SHIFT and click two cells, since the Start cell is already assumed to be the one that was originally in Edit mode.
-
Column Selection
Another type of selection supported by output grids is the Column Selection. You can select multiple columns by holding the SHIFT key and clicking on two column headers, which will select a range of adjacent columns. Alternatively, you can hold the CTRL key and click multiple column headers to select a set of non-adjacent columns.
For example, holding the SHIFT key and clicking a column will indicate the first column in a column range selection. Subsequently, holding SHIFT and clicking another column will mark the end of the column selection. All columns between the first and the last clicked column will become selected. Each consecutive click of any column (with the SHIFT key pressed) will redefine the column selection up to the most recently clicked column.
When selecting columns, you can also use the CTRL key instead of SHIFT key. The CTRL key also allows you to add and remove a desired column from the current column selection. For example, if a column is already selected and you hold CTRL while clicking the column header, then the column will become deselected.
Note that if a column is sortable (the Support Search option is enabled for the column), it will not sort the table if you click a column's header while holding the SHIFT or CTRL key.
Once you make a selection (either Cell Selection or Column Selection), hold CTRL and press C to copy the selected contents into the clipboard. This copied data can be pasted to external programs, such as Notepad or Excel, as well as to an input grid in the designer.