API functions to control Subgrid behavior starting Dynamics CRM 2015 Update 1

By | November 9, 2015


Prior to CRM2015 update 1 the only available function for interacting with the subgrids on the form was refresh(). This function is used to refresh the sub-grid records. With the release of CRM 2015 update 1, more functions were introduced to interact with the sub-grid using JavaScript.

Function list:

1. addOnLoad

2. removeOnLoad

Use the addOnLoad and removeOnLoad to attach a function/method that you would like to execute each time the grid is loaded.

This is commonly used when you want to add additional filters to set the views of the data that should be displayed in the grid.

3. getViewSelector

  • setCurrentView
  • getCurrentView
  • isVisible

When configuring the sub-grid on the form, you can choose the views that can be displayed. If you choose more than one view, the view selector is displayed.

Using these functions you can control the view currently being displayed in the grid. Most often this would be used in the onload function associated with the grid as explained above.

4. getGrid

  • getRows
  • getSelectedRows
  • getTotalRecordCount

Until this API enhancement there was no real supported way to access the rows within the subgrid. These set of functions now make it possible to get the collection of the rows being displayed in the grid and perform additional operations on them.

5. getEntity

  • getEntityReference
  • getEntityName
  • getId
  • getPrimaryAttributeValue

The functions in the point 4 above, let you get access to the grid rows, this set of functions get you the direct GUID or the entity reference of the record that is always required if you want to perform any additional operation on the rows/records.


Let us take an example to see how each of the above would actually be used through a sample code walk through

Let us set the view of the sub-grid conditionally:

  1. Associate the onload function to the grid that would have the logic to set the view


  1. Next within the function, we would set the view

var contactViewtobeSet=””;

contactViewtobeSet = {

entityType: 1039, // SavedQuery

id: “{ 00000000-0000-0000-00AA-000010001004}”,

name: “Active Contacts”


//”Contacts” is a sub-grid name.



If the sub-grid control is not configured to display the view selector, calling this method on the ViewSelector returned by the GridControl.getViewSelector will throw an error.

Let us read the record collection displayed in the grid and get the total row count

//Get an array for all rows in the sub-grid

var allGridRowData = [];

//”Contacts” is a sub-grid name.

var rows = Xrm.Page.getControl(“Contacts”).getGrid().getRows();

rows.forEach(function (row, i) {



Get the individual row record reference by

var recEntityReference = Xrm.Page.getControl(“Contacts”).getGrid().getRows().get(0).getData().getEntity().getEntityReference();

and the total records by

var rowCount = Xrm.Page.getControl(“Contacts”).getGrid().getTotalRecordCount();


With the availability of these functions, it is now much easier to communicate with the grid controls without the need to go unsupported. You can check the SDK for detailed samples on each of the functions listed in this article.

You May like to See : Tool to export your Dynamics CRM Reports in 1 click.