Editable grid objects and methods (client-side reference)

  • Article

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

You can set event handlers to subscribe to events triggered by editable grids when data is selected, changed, or saved in an editable grid. Editable grids support most of the client-side methods supported by non-editable grids. More information: Use editable grids

Note

Editable grid was introduced in the December 2016 update for Dynamics 365 (online and on-premises).

In This Topic

Editable grid events

Editable grid methods

Editable grid events

Editable grid supports the following events that you can use for registering and executing your client-side scripts. You can register for these events using the Events tab of the Microsoft Dynamics 365 page that is used to enable editable grids for an entity or a read-only grid:

  • OnRecordSelect

  • OnChange

  • OnSave

Important

Use the execution context getFormContext method to create common event handlers that can operate either on an editable grid GridCell or form field depending on where the event handler is executed. More information: getFormContext

OnRecordSelect

The OnRecordSelect event occurs when a single row (record) is selected in the editable grid. This event won't occur if a user selects different cells in the same row, or selects multiple rows.

OnChange

The OnChange event occurs when a value is changed in a cell in the editable grid and the cell loses focus. This event can also occur when an attribute value is updated using the setValue method.

OnSave

The OnSave event occurs before sending the updated information to the server, and when any of the following occurs:

  • There is a change in the record selection.

  • The user explicitly triggers a save operation using the editable grid’s save button.

  • The user applies a sort, filter, group, pagination, or navigation operation from the editable grid while there are pending changes.

Some important points to consider for the OnSave event:

  • If a user edits multiple columns of the same record in sequence, the OnSave event will only be fired once to ensure optimal performance and form behavior compatibility.

  • Editable grid and the parent form have separate save buttons. Clicking the save button in one will not save changes in the other.

  • Editable grid does not save pending changes when navigation operations are performed outside of its context. If the control has unsaved data, that data may be lost. Consequently, the OnSave event may not fire. For example, this could happen when navigating to a different record using a form lookup field or through the ribbon.

  • Pressing the refresh button in the editable grid causes it to discard any pending changes, and the OnSave event won't be fired.

  • Editable grid control does not implement an auto-save timer.

  • Editable grid suppresses duplicate detection rules.

Editable grid methods

Editable grid supports some new and most of the existing methods supported by read-only grids:

  • GridControl

  • Grid

  • GridRow

  • GridRowData

  • GridEntity

  • GridAttribute

  • GridCell

GridControl

If you know the name of the editable grid control, you can access it using the following code. For example, to access the CONTACTS subgrid in the default account form:

var contactsGrid = Xrm.Page.getControl("Contacts");

Tip

To identify the names of grid controls in the form without opening the form editor, see the information in Use browser developer tools.

Editable grid supports the following read-only grid control methods: getEntityName and getGrid.

Grid

Editable grid supports the following methods for the Grid returned by the GridControl.getGrid method: getRows, getSelectedRows, and getTotalRecordCount.

GridRow

Editable grid supports the getData method for the GridRow returned by the Grid.getRows and Grid.getSelectedRows methods.

GridRow also supports the data collection that provides ways to work with an editable grid row. See Collections (client-side reference) for information on the methods available for accessing data in a collection.

GridRowData

Editable grid supports the getEntity method for the GridRowData returned by the GridRow.getData method.

GridRowData also provides methods for retrieving information specific to a record displayed in an editable grid row, including a collection of all the attributes included in the row. Attribute data is limited to the columns presented by the editable grid. See Collections (client-side reference) for information on the methods available to access data in a collection.

GridEntity

Editable grid supports the following methods for the GridEntity returned by the GridRowData.getEntity method:

Apart from using the GridRowData.getEntity method, you can retrieve the GridEntity by directly accessing the GridRowData.entity object.

GridEntity also supports the attributes collection that provides methods of working with a collection of attributes for an entity in the editable grid. Each attribute (GridAttribute) represents the data in the cell of an editable grid, and contains a reference to all the cells associated with the attribute. See Collections (client-side reference) for information on the methods available to access data in a collection.

GridAttribute

The GridAttribute supports the following methods for attributes of a selected grid row: getName, getRequiredLevel, setRequiredLevel, getValue, and setValue.

Use the Grid.getSelectedRows method to retrieve the selected row in an editable grid.

 GridAttribute also supports the controls collection for attributes of a selected grid row, which provides methods to work with a collection of cells associated with the attribute. Each cell (GridCell) of a selected grid row is analogous to a control on a form that is tied to an attribute in an editable grid. See Collections (client-side reference) for information on the methods available to access data in a collection.

Tip

For performance reasons, a row (record) in an editable grid is not editable until the record is selected. Users must select a single record in a grid to edit it. Once a record is selected in an editable grid, Dynamics 365 internally evaluates a bunch of things including user access to the record, whether the record is active, and field validations to ensure that data security and validity are honored when you edit data. Consider using the OnRecordSelect event with the getFormContext method to access records in the grid that are in the editable state.

GridCell

In addition to setNotification and clearNotification , the GridCell supports the following methods for controls:

Note

Editable grids can’t display more than one notification at a time.

getDisabled

Returns whether the cell is disabled (read-only).

gridCellObj.getDisabled()
  • Return Value
    Type: Boolean. True if the cell is disabled, otherwise false.

setDisabled

Sets whether the cell is disabled.

gridCellObj.setDisabled(bool)

  • Arguments
    Type: Boolean. True if the cell should be disabled, otherwise false.

  • Remarks
    Enabling a read-only cell for editing can cause an error when the record is saved. If the field is considered read-only by the server, an error may occur if the value is modified. This may happen in scenarios where the user doesn't have write privileges to the record, the record is disabled, or the user doesn't have the necessary field-level security privileges.

getLabel

Returns the label of the column that contains the cell.

gridCellObj.getLabel()
  • Return Value
    Type: String. The label of the column.

See Also

Grid (read-only) objects and methods (client-side reference)
Use editable grids

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright