sc-grid
1 Purpose
sc-grid places a grid field on a form.
The sc-grid definition provides fields for setting the properties of the entire grid and of the individual columns within the grid and is fully described below.
2 Definition
sc-grid is defined by a set of name/value pair fields consisting of:
- Required system fields
- Required customizable fields
- Optional customizable fields
Note:
- Default values for fields described in the tables below are shown in bold text.
2.1 Root Level Fields
This section lists and describes the root level fields for defining the properties of the entire grid.
2.1.1 Required System Fields
Field | Valid Values | Description |
---|---|---|
componentName | sc-grid | The component name. Example: "componentName": "sc-grid" |
2.1.2 Required Customizable Fields
Field | Valid Values | Description |
---|---|---|
filter | elastic search query | The query for selecting the data source for the grid field. Example: "filter": "{'sort':[{'responseId': 'desc'}],'query':{'bool':{'must':[{'term':{'appTags':'sc-gridTestData'}},{'term':{'systemHeader.systemType':'document'}}]}}}" |
gridColumns | Array of column definitions | An array of column definitions, each defining the properties of a column within the grid. Each column definition is a set of name/value pair fields, some being required, some being optional. Section 2.2 lists and describes the fields for defining the properties of a grid column. |
name | Any value written in camel case. | Defines the name of the grid field in the document and database. Example: "name": "testScGrid" |
2.1.3 Optional Customizable Fields
Field | Valid Values | Description |
---|---|---|
disableAutoDisplay | true | Do not display selected record under the grid field. Example: "disableAutoDisplay": true |
false | Default value. Display selected record under the grid field. |
|
dropdownLabel | Any Value | The label for the resulting grid field when the "template" grid field below is defined. Example: "dropdownLabel": "Create new grid record" |
Defaults to no label is displayed. | ||
enabled | false | The grid field and its contents are greyed out. All grid field functionality is disabled Example: "enabled": false |
true | Default value. The grid field and its contents are not greyed out. All grid field functionality is enabled except for those functions that have been individually disabled. |
|
fullWidth | true | Display the grid field full width on the form. Example: "fullWidth": true |
false | Default value. Do not display the grid field full width on the form. |
|
gridOptions | Provides values that define the properties of all columns. However these can be overridden at the individual column level via its column definition. | |
columnFooterHeight | The height of the column footer row in pixels. Example: "gridOptions": {"columnFooterHeight": 50}` Defaults to 30 |
|
enableCellEdit | Sets the default value for the editable flag on each column definition if their individual enableCellEdit is not defined. Editing a cell does not trigger a save so this option is only useful to disable editing. Example: "gridOptions": {"enableCellEdit": false} Defaults to true |
|
enableColumnMenus | When enabled, displays a column menu within each column. Column menus can then be disabled on individual columns using the column definitions. Example: "gridOptions": {"enableColumnMenus": false}` Defaults to true |
|
enableColumnMoving | Enables / disables column moving on the entire grid. Example: "gridOptions": {"enableColumnMoving": false} Defaults to true |
|
enableColumnResizing | Enables / disables column resizing on the entire grid. Example: "gridOptions": {"enableColumnResizing": false} Defaults to true |
|
enableFiltering | When enabled, adds a filter box to each column header. Filtering can then be disabled on individual columns using the column definitions. Example: "gridOptions": {"enableFiltering": false} Defaults to true |
|
enableGrouping | When false, disables row grouping for the entire grid. When true, adds a "group" option to the column menu. Filtering can then be disabled on individual columns using the column definitions. Example: "gridOptions": {"enableGrouping": false} Defaults to true. |
|
enableSorting | When enabled, adds sort functions to each column header. Sorting can then be disabled on individual columns using the column definitions. Example: "gridOptions": {"gridMenuShowHideColumns": false} Defaults to true. |
|
exporterCsvFilename | Filename to use when saving the downloaded csv. Note: This may not work on all browsers. Example: "gridOptions": {"exporterCsvFilename": "sc-grid Test Data.csv"} Defaults to download.csv |
|
exporterMenuCsv | When enabled, adds csv menu items to the grid menu. Example: "gridOptions": {"exporterMenuCsv": false} Defaults to true. |
|
exporterMenuPdf | When enabled, adds pdf menu items to the grid menu. Example: "gridOptions": {"exporterMenuPdf": false} Defaults to true |
|
exporterPdfOrientation | Should be a valid orientation i.e. "landscape" or "portrait". Example: "gridOptions": {"exporterPdfOrientation": "portrait"} Defaults to "landscape". |
|
exporterPdfPageSize | Should be a valid paper size e.g. "A4", "A3", "LETTER", etc. Example: "gridOptions": {"exporterPdfOrientation": "A3"} Defaults to "A4" |
|
exporterPdfTableHeaderStyle | Sets the exported pdf table header style. Example: "gridOptions": {"exporterPdfTableHeaderStyle": {"bold": true,"color": "blue"}} Defaults to {"bold": false, "fontSize": 12, "color": "black"} |
|
gridMenuShowHideColumns | When enabled, adds show/hide columns to the grid menu. Example: "gridOptions": {"enableFiltering": false} Defaults to true. |
|
minRowsToShow | Minimum number of rows to show when the grid doesn't have a defined height. Example: "gridOptions": {"minRowsToShow": 5} Defaults to 10 |
|
rowHeight | The height of the row in pixels. Example: "gridOptions": {"rowHeight": 50} Defaults to 30 |
|
showColumnFooter | When enabled, shows a column footer which displays any column aggregates. Example: "gridOptions": {"showColumnFooter": false} Defaults to true |
|
showGridFooter | When enabled, shows a grid footer. This footer displays total rows in the grid and the number of visible rows (filtered rows). Example: "gridOptions": {"showGridFooter": true} Defaults to false. |
|
showHeader | When enabled, shows the grid header i.e. column headers, column filter boxes, etc. Example: "gridOptions": {"showHeader": false} Defaults to true |
|
grouping | Array of fields | Displays the grid field data grouped by the fields listed in the grouping array. Example: "grouping": ["currentMobilePhoneBrand", "preferredMobilePhoneColour"] |
Defaults to no grouping of grid field data. | ||
hideNoData | true | Hide the grid field if the filter returns no data. Example: "hideNoData": true |
false | Default value. Do not hide the grid field if the filter returns no data. |
|
label | Any value | Defines the name of the sc-grid field on the form i.e. the field label. Example: "label": "Test sc-drop-down" |
Defaults to the sc-grid field displays without a field label on the form. | ||
listAllDocuments | true | Ignore the gridColumns definitions and under column headings "Name" and "Description", display the summaryName and summaryDescription of documents returned by filter query. Example: "listAllDocuments": true |
false | Default value. Displays the documents returned by filter query in accordance with the gridColumns definitions. |
|
openInNewTab | true | Clicking a grid field row hyperlink will open the the record in a new tab. Example: "openInNewTab": true |
false | Default value. Clicking a grid field row hyperlink will open the the record in the current tab. |
|
refreshInterval | numeric | The grid field refresh interval expressed in seconds. Example: "refreshInterval": 30 |
Defaults to no grid field refresh. | ||
template | An array of templates | Places a drop down list of templates below the grid. Selecting a template and clicking "+" opens the template allowing the creation of new grid field records. Provides the ability to define default values for the template and the drop down display text. Provides the ability to set default values for the template fields. Example: "template": [ { "default": { "preferredMobilePhoneColour": "black" }, "name": "New grid record", "templateId": "d0d6a110-ee75-11e6-a005-d9a7d9d6cfea" } ] |
visible | false | The grid field is not visible on the form. Example: "visible": false |
true | Default value. The grid field is visible on the form. |
2.2 gridColumns Field
The "gridColumns" field in Section 2.1.2 is an array of column definitions, each defining the properties of a column within the grid.
This section lists and describes the fields for defining the properties of a column within the grid.
2.2.1 Required System Fields
Field | Valid Values | Description |
---|---|---|
field | A data source field name | The name of the data source field containing the value to display in an individual grid column. Example: "field": "dateSubmitted" Examples: showing how to reference an array field value: "field" : "assignee[0].name" "field" : "assetLocation.features[0].properties.suburb" |
2.2.2 Optional Customizable Fields
Field | Valid Values | Description |
---|---|---|
aggregationHideLabel | true | Hides the aggregation label text, only displaying the aggregation value in the column footer. Example: "aggregationHideLabel": true |
false | Default value. Displays the aggregation label and the aggregation value in the column footer. |
|
aggregationType | avg | Average the column values and display the result in the column footer. Example: "aggregationType": "uiGridConstants.aggregationTypes.avg" |
count | Count the number of column values and display the result in the column footer. Example: "aggregationType": "uiGridConstants.aggregationTypes.count" |
|
max | Determine the maximum column value and display the result in the column footer. Example: "aggregationType": "uiGridConstants.aggregationTypes.max" |
|
min | Determine the minimum column value and display the result in the column footer. Example: "aggregationType": "uiGridConstants.aggregationTypes.min" |
|
sum | Sum the column values and display the result in the column footer. Example: "aggregationType": "uiGridConstants.aggregationTypes.sum" |
|
cellFilter | Valid date format | The date/time display format to apply to each cell of an individual column. Example: "cellFilter": "date:'dd/MM/yyyy hh:mm:ss a'" |
cellTemplate | A custom template for each cell of an individual column. Can be used to define a hyperlink on an individual column. Note: By default, a hyperlink is placed on the first column. To suppress this hyperlink on the first column, use: "cellTemplate": "" |
|
cellTooltip | true | Display a tooltip on cell mouseover. If true, the cell value is shown in the tooltip (useful if cells have long values). Example: "cellTooltip": true |
false | Default value. Do not display a tooltip on cell mouseover. |
|
displayName | Any value | The column name shown in the header. If not provided then one is generated using the name of the source field. Example: "displayName": "Phone Colour" |
enableCellEdit | false | Disables editing of column data. Example: "enableCellEdit": false |
true | Default value. Enables editing of column data. Note: Editing a cell does not trigger a save so this option is only useful to disable editing. |
|
enableColumnMenu | false | Disables the menu for an individual column when column menus are enabled for the entire grid. Example: "enableColumnMenu": false |
true | Enables the menu for an individual column when column menus are enabled for the entire grid. Example: "enableColumnMenu": true |
|
Defaults to the value set for gridOptions.enableColumnMenus. | ||
Note: If column menus are disabled for the entire grid, then no column menus are enabled irrespective of the value of this field. |
||
enableColumnMoving | false | Disable moving on an individual column when column moving is enabled for the entire grid. Example: "enableColumnMoving": false |
true | Enable moving on an individual column when column moving is disabled for the entire grid. Example: "enableColumnMoving": true |
|
Defaults to the value set for gridOptions.enableColumnMoving. | ||
Note: If column moving is disabled for the entire grid, then no column moving is enabled irrespective of the value of this field. |
||
enableColumnResizing | false | Disable resizing on an individual column when column resizing is enabled for the entire grid. Example: "enableColumnResizing": false |
true | Enable resizing on an individual column when column resizing is disabled for the entire grid. Example: "enableColumnResizing": true |
|
Defaults to the value set for gridOptions.enableColumnResizing. | ||
Note: If column resizing is disabled for the entire grid, then no column resizing is enabled irrespective of the value of this field. |
||
enableFiltering | false | Disables filtering for an individual column when filtering is enabled for the entire grid. Example: "enableFiltering": false |
true | Enables filtering for an individual column when filtering is enabled for the entire grid. Example: "enableFiltering": true |
|
Defaults to the value set for gridOptions.enableFiltering. | ||
Note: If filtering is disabled for the entire grid, then no column filtering is enabled irrespective of the value of this field. |
||
enableGrouping | false | Disables grouping for an individual column when grouping is enabled for the entire grid. Example: "enableGrouping": false |
true | Enables grouping for an individual column when filtering is enabled for the entire grid. Example: "enableGrouping": true |
|
Defaults to the value set for gridOptions.enableGrouping. | ||
Note: If grouping is disabled for the entire grid, then no column grouping is enabled irrespective of the value of this field. | ||
enableHiding | false | Disables hiding an individual column on the column menu and the grid menu. Example: "enableHiding": false |
true | Default value. Enables hiding an individual column on the column menu. |
|
enableSorting | false | Disables the sorting for an individual column when sorting has been enabled for the entire grid. Example: "enableSorting": false |
true | Enables the sorting for an individual column when sorting has been enabled for the entire grid. Example: "enableSorting": true |
|
Defaults to the value set for gridOptions.enableSorting. | ||
Note: If sorting is disabled for the entire grid, then no column sorting is enabled irrespective of the value of this field. |
||
exporterPdfAlign | The alignment of an individual column when exported into a pdf. | |
left | Example:"exporterPdfAlign": "left" |
|
right | Example:"exporterPdfAlign": "right" |
|
center | Example:"exporterPdfAlign": "center" |
|
exporterSuppressExport | true | Suppress the export of an individual column. Example: "exporterSuppressExport": true |
false | Default value. Does not suppress the export of an individual column. |
|
filter | Use to specify a single filter on an individual column. | |
dateFilter | Display date/time values in local time. Example: "filter": "dateFilter" |
|
arrayFilter | Display all values when a field has an array of values. Example: "filter": "arrayFilter" |
|
filterCellFiltered | true | Apply the cellFilter before applying "search" filters. Example: "filterCellFiltered": true |
false | Default value. Do not apply the cellFilter before applying "search" filters. |
|
groupingShowAggregationMenu | false | Hides the aggregation menu for an individual column. Example: "groupingShowAggregationMenu": false |
true | Default value. Shows the aggregation menu for an individual column. |
|
groupingShowGroupingMenu | false | Hides the grouping menu (group and ungroup) for an individual column. Example: "groupingShowGroupingMenu": false |
true | Default value. Shows the grouping menu for an individual column. |
|
headerTooltip | true | Display a tooltip on header cell mouseover. Shows the displayName value as the tooltip (useful if headers have long values). Example: "headerTooltip": true |
false | Default value. Do not display a tooltip on header cell mouseover. |
|
sortCellFiltered | true | Apply the cellFilter before sorting the column data. Example: "sortCellFiltered": true |
false | Default value. Do not apply the cellFilter before sorting the column data. |
|
Note: uiGrid will assume that the displayed value is a string, and perform an alpha sort. |
||
type | The data type of the column. Used in sorting. If not provided then the grid will guess the type. Useful if the grid guessing is not satisfactory. |
|
boolean | Example:"Type": "boolean" |
|
date | Example:"Type": "date" |
|
number | Example:"Type": "number" |
|
object | Example:"Type": "object" |
|
string | Example:"Type": "string" |
|
visible | false | The column is not visible. Example: "visible": false |
true | Default value. The column is visible. |
|
width | Numeric | The column width as a proportion of the total width. Example: "width": 2 If the width values of 4 columns are defined as 1, 1, 2 and 1 respectively, then:
|
1 | Default value. |
Examples
Example 1
sc-grid with only its required system fields and required customizable fields defined.
{
"componentName": "sc-grid",
"label": "Test sc-grid",
"name": "testScGrid",
"filter": "{'sort':[{'responseId': 'desc'}],'query':{'bool':{'must':[{'term':{'appTags':'sc-gridTestData'}},{'term':{'systemHeader.systemType':'document'}}]}}}",
"gridColumns": [
{
"displayName": "ID",
"field": "responseId",
"width": 1
},
{
"field": "respondent.name",
"width": 6,
"displayName": "Respondent",
"filter": "arrayFilter"
},
{
"displayName": "Date Submitted",
"field": "dateSubmitted",
"width": 3,
"cellFilter": "date:'dd/MM/yyyy hh:mm a'",
"filter": "dateFilter"
},
{
"field": "mobileDevicesUsed",
"width": 4,
"displayName": "Mobile Devices",
"filter": "arrayFilter"
},
{
"field": "mobileDeviceUsage",
"width": 3,
"displayName": "Usage (hrs/day)"
},
{
"field": "currentMobilePhoneBrand",
"width": 3,
"displayName": "Mobile Phone Brand"
},
{
"field": "preferredMobilePhoneColour",
"width": 2,
"displayName": "Phone Colour"
}
]
}
Example 2
sc-grid with all required fields defined and with:
-
The following optional fields defined for the entire grid:
- "disableAutoDisplay": true
- "dropdownLabel": "Create new grid record"
- "fullWidth": true
- "gridOptions": {"minRowsToShow": 5}
- "gridOptions": {"showGridFooter": true}
- "label": "Test sc-grid"
- "openInNewTab": true
- "template":
-
The following optional fields defined for the "ID" grid column definition:
- "displayName": "ID"
- "width": 1
-
The following optional fields defined for the "Respondent" grid column definition:
- "displayName": "Respondent"
- "width": 6
- "filter": "arrayFilter"
-
The following optional fields defined for the "Date Submitted" grid column definition:
- "cellFilter": "date:'dd/MM/yyyy hh:mm a'"
- "displayName": "Date Submitted"
- "filter": "dateFilter"
- "width": 3
-
The following optional fields defined for the "Mobile Devices" grid column definition:
- "displayName": "Mobile Devices"
- "filter": "arrayFilter"
- "width": 4
-
The following optional fields defined for the "Usage (hrs/day)" grid column definition:
- "aggregationType": "uiGridConstants.aggregationTypes.avg"
- "displayName": "Usage (hrs/day)"
- "headerTooltip": true
- "type": "number"
- "width": 3
-
The following optional fields defined for the "Mobile Phone Brand" grid column definition:
- "displayName": "Mobile Phone Brand"
- "width": 3
-
The following optional fields defined for the "Phone Colour" grid column definition:
- "displayName": "Phone Colour"
- "width": 2
{
"componentName": "sc-grid",
"label": "Test sc-grid",
"name": "testScGrid3",
"disableAutoDisplay": true,
"dropdownLabel": "Create new grid record",
"fullWidth": true,
"gridOptions": {
"showGridFooter": true,
"minRowsToShow": 4
},
"filter": "{'sort':[{'responseId': 'desc'}],'query':{'bool':{'must':[{'term':{'appTags':'sc-gridTestData'}},{'term':{'systemHeader.systemType':'document'}}]}}}",
"gridColumns": [
{
"displayName": "ID",
"field": "responseId",
"width": 1
},
{
"field": "respondent.name",
"width": 6,
"displayName": "Respondent",
"filter": "arrayFilter"
},
{
"displayName": "Date Submitted",
"field": "dateSubmitted",
"width": 3,
"cellFilter": "date:'dd/MM/yyyy hh:mm a'",
"filter": "dateFilter"
},
{
"field": "mobileDevicesUsed",
"displayName": "Mobile Devices",
"filter": "arrayFilter",
"width": 4
},
{
"field": "mobileDeviceUsage",
"width": 3,
"displayName": "Usage (hrs/day)",
"type": "number",
"aggregationType": "uiGridConstants.aggregationTypes.avg",
"headerTooltip": true
},
{
"field": "currentMobilePhoneBrand",
"width": 3,
"displayName": "Mobile Phone Brand"
},
{
"field": "preferredMobilePhoneColour",
"width": 2,
"displayName": "Phone Colour"
}
],
"template": [
{
"default": {
"preferredMobilePhoneColour": "black"
},
"name": "New grid record",
"templateId": "d0d6a110-ee75-11e6-a005-d9a7d9d6cfea"
}
]
}
Resulting grid field: