JavaScript Model Changes || New Client APIs || Deprecated Client APIs
There are significant changes made to Client APIs in Dynamics 365 version 9.0 release. Table below lists four main changes happened in this release:
| Execution Context | Use execution context to retrieve form or grid context instead of using Xrm.Page which is deprecated in this release |
| Global Context | New API added to Xrm.Utility object to retrieve information specific to organization, user or client where script is executed instead of using Xrm.Page.context which is deprecated in this release |
| New Client APIs | Number of new namespaces and APIs introduced with this release
New namespaces:
- Xrm.Device
- Xrm.Encoding
- Xrm.Navigation
- Xrm.WebApi
New APIs in existing namespaces:
- formContext.data – onload, isValid, saveOptions, saveMode
- formContext.data.entity – getEntityReference, isValid
- formContext.ui – onload event handlers
- Xrm.Utility – getEntityMetadata, getGlobalContext, lookupObjects, showProgressIndicator, closeProgressIndicator
Refer link for complete list. |
| Deprecated APIs | Some of client APIs are deprecated:
- Xrm.Page
- Xrm.Page.context
- GridRow.getData
- GridRowData.getEntity
- Xrm.Mobile.offline
- parent.Xrm
- Xrm.Utility.alertDialog
- Xrm.Utility.confirmDialog
- Xrm.Utility.openEntityForm
- Xrm.Utility.openQuickCreate
- Xrm.Utility.openWebResource
Refer section Deprecated Client APIs below for more details.
|
JavaScript Model Changes:
At root of Client API object model, we have executions object and Xrm object as shown below:
Let’s have a look at each of these in detail:
1. Execution Context – Context which is passed when an event occurs on a form or grid which you can use it in your event handler to determine
formContext,
gridContext or manage the save event
We can pass execution context through UI or code:
- Pass through UI – Execution context is an optional parameter and can be passed through UI at time of defining event handler under handler properties. Use “Pass execution context as first parameter” option to pass execution context to JavaScript function
- Pass through code – Event handlers which cannot be defined from UI, can be defined from code. The execution context is automatically passed as the first parameter to functions set using code. Below is the example:
- addOnChange – formContext.getAttribute(arg).addOnChange(myFunction)
- removeOnChange – formContext.getAttribute(arg).removeOnChange(myFunction)
FUNCTION MYFUNCTION(EXECUTIONCONTEXT)
{
//FIRST PARAMETER PASSED AS EXECUTION CONTEXT
}
| Earlier
function displayName()
{
var firstName = Xrm.Page.getAttribute(“firstname”).getValue();
var lastName = Xrm.Page.getAttribute(“lastname”).getValue();
console.log(firstName + ” ” + lastName);
}
|
| Now
function displayName(executionContext)
{
var formContext = executionContext.getFormContext(); // get formContext
// use formContext instead of Xrm.Page
var firstName = formContext.getAttribute(“firstname”).getValue();
var lastName = formContext.getAttribute(“lastname”).getValue();
console.log(firstName + ” ” + lastName);
}
|
2. Form Context (Replaced Page) – Context provides reference to form or any item on form against which current code is executed. Form Context can be retrieved using executionContext.getFormContext Form context replaced Xrm.Page which is deprecated in this release and was used to represent form or any item on form earlier.
Form Context Object Model:
For more details please refer link
3. Grid Context (Replace Xrm.Page) – Context provides reference to grid or sub-grid on form against which code is executed. Grid context can be retrieved from execution context based on where code is being executed. Grid context also replaced Xrm.Page which was used to represent grid or sub grid on form earlier.
| Earlier
function doSomething()
{
var contactsSubgrid = Xrm.Page.getControl(“Contacts”);
}
|
| Now
1) Code is executed on form event
function doSomething(executionContext) {
var formContext = executionContext.getFormContext(); // get the form Context
var gridContext = formContext.getControl(“Contacts”); // get the grid context
// Perform operations on the subgrid
}
2) Code is executed on grid event
function doSomething(executionContext) {
var formContext = executionContext.getFormContext(); // get the form Context
var gridContext = formContext.getControl(“Contacts”); // get the grid context
// Perform operations on the subgrid
}
|
Some other methods:
| Grid | Earlier
Xrm.Page.getControl(“Contacts”).getGrid();
Now
gridContext.getGrid();
//where griContext = formContext.getControl(“Contacts”);
|
| GridRow | Earlier
Xrm.Page.getControl(“Contacts”).getGrid().getRows();
Now
gridContext.getGrid().getRows();
|
| GridRowData | Earlier
Xrm.Page.getControl(“Contacts”).getGrid().getRows().get(0).getData()
Now
gridContext.getGrid().getRows().get(0).data
Note – getDate() is deprecated in this release
|
| GridEntity | Earlier
Xrm.Page.getControl(“Contacts”).getGrid().getRows().get(0).getEntity()
Now
gridContext.getGrid().getRows().get(0).entity
Note – getEntity() is deprecated in this release
|
4. Xrm Object – Xrm object is globally available which provides methods to use device capabilities, navigation settings, information specific to organization or user and offline capabilities without having to use execution context in Client API. In this release Xrm object is updated to have new namespaces and new APIs in existing namespaces.
New Xrm Object Model:
New Namespaces:
- Device – Provides methods to use native device capabilities of mobile devices.
- captureAudio
- captureImage
- captureVideo
- getBarcodeValue
- getCurrentPosition
- pickFile
- Encoding – Provides methods to encode strings.
- xmlAttributeEncode
- xmlEncode
- Navigation – Provides methods for navigating forms and items in Customer Engagement.
- openAlertDialog
- openConfirmDialog
- openErrorDialog
- openFile
- openForm
- openUrl
- openWebResource
- WebApi – Provides methods to use Web API to create, manage records and execute Web API actions and functions. Comes with offline capabilities also for mobile clients.
Properties:
online – perform actions or functions when connect to server (online mode)
offline – perform actions or functions when offline with mobile clients
Methods:
createRecord – Creates an entity record
deleteRecord – Deletes an entity record
retrieveRecord – Retrieves an entity record
retrieveMultipleRecords – Retrieves a collection of entity records
updateRecord – Updates an entity record
isAvaiableOffline – Returns a boolean value indicating whether an entity is present in user’s profile and is currently available for use in offline mode
execute – Execute a single action, function, or CRUD operation
executeMultiple – Execute a collection of action, function, or CRUD operations
Refer to my
blog for more details on
Xrm.WebApi
Deprecated Client APIs:
Following are deprecated Client APIs in this release which will be replaced with replacement client API mentioned. Deprecated Client APIs will continue to be available and supported until they are officially removed from a future major release of Dynamics 365.
Deprecated Client API
Deprecated:
|
|
