---
category: [Administration & Integrations, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Custom Integrations & Apps, Platform and Product Extensions/Workday Extend]
keyword: [Extend, Presentation Components, widgets, tags, UI components]
nav: wcp_docs
parent_url: /wcp_docs/
title: grid
layout: subsection
wd_wcptag: grid
---
Displays data in a table format comprised of rows and columns. A grid on an edit page enables users to add, modify, and delete row data.
Use `grid` on view and edit pages.
Grids on view pages support assistive technology. Screen readers can announce:
- Column header names.
- Row header names.
- Column sort order (ascending or descending).
- Instructions for sorting a column.
- Required fields.
Support for assistive technology and pagination options for large tables don’t apply to edit grids.
## Usage
See [Concept: grid](/wcp_docs/tgx1652476064414.html).
## Mobile Support
Android, iOS
## Attributes
- rows
Data type: dynamicBinding-List
(Required) A list of data elements that corresponds to each row of data in the grid. Use `rowVariableName` to reference the row data. Example: `<% workersEndpoint.data %>`
- rowVariableName
Data type: string
(Required) The variable name you can reference to bind the value at the current row data. Specify only alphanumeric and underscore characters.
Use `rowVariableName` in the cell template to reference the runtime value at the current row data. Example: If
```
"rowVariableName": "thisRow”
```
then a cell template can reference the data to populate the respective cell with:
```
"cellTemplate": {
"type": "text",
"value": "<% thisRow.descriptor %>"
}
```
- columns
Data type: list of columns
(Required for static columns) Contains `column` objects that define static columns in the grid. The order of the columns depends on how you ordered them in `columns[]`.
`columns` and `dynamicColumns` are mutually exclusive.
See [column](/wcp_docs/awa1518457187337.html) and "Defining Columns" in [Concept: grid](/wcp_docs/tgx1652476064414.html).
- cellTemplates
Data type: list of cellTemplate objects
(Required for dynamic columns) Contains `cellTemplate` objects. Each `cellTemplate` specifies a template for a type of column, and contains these attributes:
- id
Data type: binding-String
Unique identifier used for debugging purposes only.
Notes:
- The `id` must start with a letter.
- The `id` must be unique per page.
- template
Data type: tag
(Required) The template tag for the cells of a dynamic column. Example:
```
"template": {
"type": "number"
}
```
- templateId
Data type: string
(Required) A string value of the `templateId` attribute binding in `dynamicColumns`. The column data specified in the `columns` attribute of `dynamicColumns` must contain the `templateId` value.
Example: If `dynamicColumns` specifies `"templateId": "type"` and the column data contains a column of string type, a `cellTemplate` in `cellTemplates[]` must specify `"templateId": "string"`.
See [dynamicColumns](/wcp_docs/kfa1570080048883.html) and "Defining Dynamic Columns" in [Concept: grid](/wcp_docs/tgx1652476064414.html).
- dynamicColumns
Data type: dynamicColumns
(Required for dynamic columns) Contains column information for generating dynamic columns. The grid dynamically generates the column label, the cell widget, and the value in each cell. The order of the generated columns depends on the order of the column data from the inbound endpoint.
Use `dynamicColumns` with the `cellTemplates` attribute of the `grid` tag.
`columns` and `dynamicColumns` are mutually exclusive.
See [dynamicColumns](/wcp_docs/kfa1570080048883.html) and "Defining Dynamic Columns" in [Concept: grid](/wcp_docs/tgx1652476064414.html).
- autoPaging
Data type: boolean
When true, the grid automatically paginates data when there are more than 50 rows of results.
Use `autoPaging` only on view pages.
To improve grid performance, enable `autoPaging` when you call fast endpoints that return high volumes of data in a single API call. The grid displays the first 50 rows of results with the initial API call, then calls the endpoint again each time the user scrolls down to load more results. Because the endpoint could get called multiple times as the user scrolls down, Workday doesn't recommend enabling `autoPaging` for slow endpoints.
For endpoints that return paginated data, use the `pagingInfo` attribute to paginate grid results.
The `autoPaging` attribute is mutually exclusive with `pagingInfo`.
- configurable
Data type: boolean
Set `configurable` to false if you set that preloads files using `multiViewStylingEnabled` to true. Use the `configurable` attribute only with the `multiViewStylingEnabled` attribute. Default is true.
- currentRowVariable
Data type: string
The variable name that represents the current row in a grid. Specify only alphanumeric and underscore characters.
The current row object of a grid contains these properties:
- `selected` - A boolean indicating whether the user marked the selection check box on the current row. If you want to use `.selected`, you must set `selectionEnabled` to true.
- `childrenMap` - A map containing the cells on the row. You can reference each cell with the column ID. Example: `.childrenMap.`
This sample `excel` attribute in a grid `column` uses the `currentRowVariable`, whose value is currentRow:
```
"excel": {
"value": "<% currentRow.childrenMap.someColumnId.value %>",
}
```
This sample `onSend` event handler of an outbound endpoint uses the `currentRowVariable`, whose value is currentRow. The outbound endpoint sends the current grid row data only if the current row is selected.
```
{
"baseUrlType": "testServer",
"authType": "noauth",
"name": "updateSkills",
"url": "/post",
"onSend": "<% currentRow.selected ? self.data : null %>"
}
```
Note: When you use `currentRowVariable` in an `onSend` event handler, set the `isArrayOutBinding` attribute of the grid to false. This setting calls the endpoint for each row object, which makes the row instance available in `currentRowVariable`.
Note: You can't use `currentRowVariable` in a `valueOutBinding` with PMD Scripting.
- deleteEndPoint
Data type: string
The name of the endpoint to use for deleting a row from the grid. Use only on edit pages.
See Deleting Row Data in [Concept: grid](/wcp_docs/tgx1652476064414.html).
- doNotAdd
Data type: dynamicBinding-Boolean
If true, users can't add rows to the grid. If false, the grid on an edit page displays a column with the plus icon, which enables users to add a row at the top of the grid. The default is false. Use only on edit pages.
Notes:
- To enable users to add a row below a specific row, set `showRowMover` to true.
- The `selectionEnabled` and `maxRowSelection` settings override the `doNotAdd` attribute. If you set `selectionEnabled` to true and `doNotAdd` is false, the user sees the selection check boxes.
- doNotPutInTab
Data type: boolean
If false, the page displays this grid in a tab on the bottom of the page. The default is true (by default, a grid doesn't display in a tab). The tabbed tags display in the order that they appear in the PMD.
Notes:
- Do not use the `doNotPutInTab` attribute with pages that use `tabs[ ]`.
- The tabs appear when:
- There are multiple tabbed tags (such as grids or panelLists with `doNotPutInTab` as false).
- There is at least 1 non-tabbed tag.
- doNotRemove
Data type: dynamicBinding-Boolean
If true, users can't delete any row from the grid. If false, the grid on an edit page displays a column with the minus icon for each row, which enables users to delete the row from the grid. The default is false. Use only on edit pages.
Note: The `selectionEnabled` and `maxRowSelection` settings override the `doNotRemove` attribute. If you set `selectionEnabled` to true and `doNotRemove` is false, the user sees the selection check boxes.
Example:
```
"doNotRemove": "<% size(locationGrid.rows) <= 2 %>"
```
- doNotRemoveRow
Data type: binding-Boolean
If true, users can't delete a specific row on the grid. Use `doNotRemoveRow` only on edit pages. Example:
```
"doNotRemoveRow": "<% list:size(expenseGrid.rows) >= 1 %>"
```
- enabled
Data type: dynamicBinding-Boolean
If true, users can enter values on the widget. If false, users can only view the widget.
- excelExportEnabled
Data type: booleanScript
If true, the grid displays the Export to Excel icon, which enables users to export the entire grid data to an Excel spreadsheet. The default is false.
Use `excelExportEnabled` only on view pages.
- id
Data type: binding-String
Unique identifier used to reference this widget from other tags.
Notes:
- The `id` must start with a letter.
- The `id` must be unique per page.
- To enable other widgets to reference this widget `id`, place this widget before the other widgets on the PMD. The PMD validation returns an "Undefined variable" error if it doesn't find a previously defined `id` in the PMD.
- Workday recommends that you include the `id` in your tag definitions for debugging purposes.
- indexVariableName
Data type: string
A variable name used as an index for looping over grid elements on an edit page. Specify only alphanumeric and underscore characters.
Example:
```
{
"type": "grid",
"label": "Selectable Grid",
"selectionEnabled": "true",
"isArrayOutBinding": "true",
"indexVariableName": "i",
"maxRowSelection": "2",
"rows": "<% gridData.data %>",
"columns": [
{
"type": "column",
"columnId": "0",
"cellTemplate": {
"type": "text",
"value": "<% i %>"
}
}
]
}
```
The variable "i" is the value of `indexVariableName`.
Consider these guidelines:
- The `indexVariableName` is helpful when using `grid` on a view page. The `indexVariableName` doesn't reflect the grid index when rows are removed.
- If you need to reference a row when you use `grid` on an edit page, you can configure a `hidden` tag in the grid with some value. When needed, you can look up the row that contains the specific hidden value. Example: Assume the `hidden` tag is the first child of a container in the grid column:
```
myGrid.rows.find(row => row.myColumn.children[0].value == 'someValue')
```
- isArrayOutBinding
Data type: binding-Boolean
Determines whether or not the entire grid sends together for persistence. When false, individual rows send separately. Use only on edit pages.
- label
Data type: dynamicBinding-String
Text that displays beside or above most widgets. Often used in simple widgets that include inputs.
The maximum number of characters is 255.
- maxRowSelection
Data type: binding-Integer
The maximum number of rows a user can select on the grid. When the user reaches the selection limit, the grid disables the rest of the check boxes.
If you set `selectionEnabled` to true, also set `maxRowSelection` to a value greater than 1.
Use `selectionEnabled`, `maxRowSelection`, and `rowSelected` only on edit pages.
- minOccurs
Data type: binding-Integer
The minimum number of rows on the grid. Use only on edit pages.
You can only delete a row if the row count is above the minimum set by `minOccurs`. When the row count drops to or below the `minOccurs`value, you can't delete any more rows.
- multiViewStylingEnabled
Data type: boolean
If true, the grid displays with minimal styling, without borders and lines between columns. To use this attribute, you must:
- Set the `configurable` attribute to false.
- Use on view pages only.
- pagingInfo
Data type: pagingInfo
Specifies how to fetch the next page or set of data that displays on the grid. The presence of the `autoPaging` or `pagingInfo` attributes indicates that the grid fetches paginated data. By default, the grid fetches as much data as the client can handle, without pagination.
Use `pagingInfo` only on view pages.
The `pagingInfo` attribute is mutually exclusive with `autoPaging`.
Example:
```
"pagingInfo": {
"endPoint": "<% endpoints.workersEndpoint %>",
"rowCount": "<% workersEndpoint.total %>",
"data": "<% workersEndpoint.data %>"
}
```
`pagingInfo` contains these required attributes:
- endPoint
Data type: binding-Endpoint
(Required) The reference to the inbound endpoint that fetches paginated data. Specify `<% endpoints.anEndpointName %>`.
The inbound endpoint must provide pagination parameters. The pagination parameters are typically named `limit` and `offset`. The `limit` parameter is the maximum number of objects in a single response. The `offset` parameter is the positional index of the first object in a response collection. When you define the endpoint `url` in `endPoints[]`, specify the limit and offset parameters. Use `pagingVariables.limit` and `pagingVariables.offset` to pass the limit and offset values across multiple requests.
Each time a paging request triggers, the request automatically updates the `pagingVariables.limit` and `pagingVariables.offset` values for the grid. Each grid maintains separate `pagingVariables` from other grids.
The `url` for this sample `workers` endpoint includes the `limit` and `offset` parameters. When the PMD initially calls the endpoint, it sets `pagingVariables.limit` to 30 and `pagingVariables.offset` to 0. When the app user reaches the last fetched data on the grid and pages down, the grid then calls the endpoint with the appropriate `limit` and `offset` values.
```
"endPoints": [
{
"baseUrlType": "workday-staffing",
"name": "workersEndpoint",
"authType": "sso",
"url": "<%
var limit = pagingVariables.limit ?: 30;
var offset = pagingVariables.offset ?: 0;
'/workers?limit=' + limit + '&offset=' + offset;
%>"
}
]
```
The `pagingVariables.limit` and `pagingVariables.offset` are string variables. To set their initial values, use the conditional operator to check their empty state and assign the value, as shown in the sample `url`. Subsequent grid page requests automatically assign the offset value.
- rowCount
Data type: binding-Integer
(Required) The total count returned by the endpoint, typically the `total` field in the endpoint response. The grid displays this total at the top, and uses the total to allocate the spacing on the vertical scroll bar. The total number can be greater than the number of rows in the paginated data.
- data
Data type: binding-List
(Required) The paginated data returned by the endpoint. This list is typically the `data` collection returned by the endpoint.
- render
Data type: binding-Boolean
If true, this tag renders as a widget on the page. If false, the loaded page doesn't add this tag or its children. The default is true.
Unlike the `visible` attribute, when `render` is false, other tags on the page can't reference this tag or widget on edit pages. On view pages, a tag can't reference other tags regardless of the `render` attribute value.
- rowSelected
Data type: binding-Boolean
If true, the grid loads each row as selected. When the grid loads, each row displays with a selected check box. The grid evaluates this attribute for each row, and selects the row when the binding evaluates to true.
You can only use `rowSelected` if you set `selectionEnabled` to true.
The `currentRow.selected` property returns a boolean indicating whether or not the row is selected.
Use `selectionEnabled`, `maxRowSelection`, and `rowSelected` only on edit pages.
- selectionEnabled
Data type: binding-Boolean
If true, the grid displays a check box column for selecting rows. The default is false.
Notes:
- If you set `selectionEnabled` to true, also set `maxRowSelection` to a value greater than 1.
- The `selectionEnabled` attribute overrides the `doNotAdd` and `doNotRemove` attributes. If you set `selectionEnabled` to true, the user sees the selection check boxes. They won't see the + nor - icons, regardless of the `doNotAdd` and `doNotRemove` settings.
- Use `selectionEnabled`, `maxRowSelection`, and `rowSelected` only on edit pages.
- To check whether the user selected a row, use the `currentRowVariable.selected` property.
- showRowMover
Data type: boolean
If true, the editable grid displays the Order column and adds the + icon on each row. The Order column enables users to move rows up or down. The + row icon enables users to add a row below a specific row. Use only on edit pages.
Note: The + row icons won't display if `doNotAdd` is true.
- sortOrder
Data type: binding-String
When you set `sorted` to true on the `section` or `fieldSet` parent of this widget, the `sortOrder` attribute determines the order of this widget within its parent. The sort order is relative to the siblings of the widget.
Typical values are "a", "b", "c", and so on. Example: The widget with `"sortOrder": "a"` displays before the widget with `"sortOrder": "b"`.
Note: The `sortOrder` doesn't apply to sorting data on the widget. `sortOrder` only applies to the placement order of the widgets within the parent widget.
- visible
Data type: dynamicBinding-Boolean
If true, the widget generated by this tag is visible. If false, this tag and its children tags aren't visible. This tag provides the ability to display or hide the widget dynamically based on user interactions on the page. The default is true. Unlike the `render` attribute, the generated widget persists on the page even when `visible` is false.
Notes:
- When the widget or field you’re hiding changes on the page, you must include it inside a `fieldSet`.
- When the `visible` attribute is false for this widget on an edit page, the outbound endpoint doesn't include the `valueOutBinding` or `valuesOut` data of the widget in the payload. To include the `valueOutBinding` or `valuesOut` data in the payload, use the `onSend` event handler.
## PMD Scripting Events
- onRowAdd
Triggers when the user adds a grid row on an edit page. Applies only to `grid` widgets that enable users to add grid rows. The `doNotAdd` attribute of the grid must be false (default).
- onRowRemove
Triggers when the user removes a grid row on an edit page. Applies only to `grid` widgets that enable users to remove grid rows. The `doNotRemove` attribute of the grid must be false (default).
- onRowSelect
Triggers when the user selects or unselects a grid row. Applies only to `grid` widgets that enable users to select grid rows. The `selectionEnabled` attribute of the grid must be true. Also set the `maxRowSelection` attribute.
## PMD Scripting Methods
- Grid Widget Methods
- addRow(int index)
Return type: `void`
Description: Adds a row at the specified index position. The index must be between 0 and the `grid` size.
- anyUpdated()
Return type: `boolean`
Description: If true, any descendant in this container widget is updated.
- getChildren()
Return type: `List`
Description: Returns a list containing all children of this container widget.
- getDoNotAdd()
Return type: `boolean`
Description: If true, this grid doesn't allow the grid user to add rows.
- getDoNotRemove()
Return type: `boolean`
Description: If true, this grid doesn't allow the grid user to remove rows.
- getLabel()
Return type: `string`
Description: Returns the grid label.
- getRows()
Return type: `List`
Description: Returns all rows of this grid as a list of grid row objects. Same as getChildren().
- getSelectedRows()
Return type: `List`
Description: Returns all selected rows of this grid as a list of grid row objects.
- getSubtotal(String columnId)
Return type: `BigDecimal`
Description: Returns the subtotal of the specified column.
- isVisible()
Return type: `boolean`
Description: If true, this widget is visible.
- removeRow(int index)
Return type: `void`
Description: Removes the row at the specified index position. The index must be between 0 and the `grid` size.
- setDoNotAdd(boolean doNotAdd)
Return type: `void`
Description: Enables or disables the ability to add rows to the grid.
- setDoNotRemove(boolean doNotRemove)
Return type: `void`
Description: Enables or disables the ability to remove rows from the grid.
- setLabel(String label)
Return type: `void`
Description: Sets the grid label.
- setRows(List newValue)
Return type: `void`
Description: Sets the new data source to refresh the grid.
- setVisible(boolean visible)
Return type: `void`
Description: Display or hides this widget. Ensure that this widget is inside a `fieldSet`.
If you need to change the visibility of a `grid`, ensure that it's inside a `fieldSet`.
- Grid Row Widget Methods
- anyUpdated()
Return type: `boolean`
Description: If true, any descendant in this container widget is updated.
- get(String childId)
Return type: `Widget`
Description: Returns the child widget with the specified tag `id` on this grid row. For the childId input argument:
- If the column `cellTemplate` has only 1 tag, specify the `id` of the `column`.
- If the column `cellTemplate` has a container widget such as a `section` or `fIeldSet`, specify the path to the `id` of the appropriate child tag.
Instead of using the `childrenMap` property of a grid row or cell, use the `get(childId)` method to access the children widgets directly. Example:
```
// Assume row is a grid row instance, and the grid has column1 and column2.
// column2 contains innserSection with a numberCell.
// Direct access to the numberCell value:
row.column1.value + (row.column2.innerSection.numberCell.value ?? '');
// Equivalent call using childrenMap:
row.childrenMap.column1.value + (row.childrenMap.column2.childrenMap.innerSection.childrenMap.numberCell.value ?? '')
```
Different ways to call the `get(childId)` method:
- gridRow.childId
Example:
```
self.value = dataGrid.rows.map(row => {
row.column1.value + (row.column2.column2Section.textCell.value ?? '')
}).join(',');
```
- gridRow['childId ']
Example:
```
self.value = dataGrid.rows.map(row => {
row['column1'].value + (row['column2']['column2Section']['numberCell'].value ?? '')
}).join(',');
```
- gridRow.get('childId ')
Example:
```
self.value = dataGrid.rows.map(row => {
row.get('column1').value + (row.get('column2').get('column2Section').get('textCell').value ?? '')
}).join(',');
```
- getChildren()
Return type: `List`
Description: Returns a list containing all children of this container widget.
- getChildrenMap()
Return type: `Map`
Description: Returns a map containing all children of this grid row. To identify each cell on the grid row, the map uses the `columnId` attribute of the grid `column`.
- isSelected()
Return type: `boolean`
Description: If true, this grid row is selected.