Skip to content

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:

  1. 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:
  • Columns 1, 2, & 4 are of equal width, each being 1/5 of the total width.
  • Column 3 width is double the width of column 1, being 2/5 of the total width.
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:

  1. 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":

  2. The following optional fields defined for the "ID" grid column definition:

    • "displayName": "ID"
    • "width": 1

  3. The following optional fields defined for the "Respondent" grid column definition:

    • "displayName": "Respondent"
    • "width": 6
    • "filter": "arrayFilter"

  4. 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

  5. The following optional fields defined for the "Mobile Devices" grid column definition:

    • "displayName": "Mobile Devices"
    • "filter": "arrayFilter"
    • "width": 4

  6. 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

  7. The following optional fields defined for the "Mobile Phone Brand" grid column definition:

    • "displayName": "Mobile Phone Brand"
    • "width": 3

  8. 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:

alt text