Understanding Xrm.Page client side model in Microsoft Dynamics 365 Customer Engagement (CRM)

In Microsoft Dynamics 365 CRM, javascript is the backbone of client-side customization. From show/hide of fields to locking/unlocking, getting/setting values of fields etc are coded in javascript. This make it critical to understand and get the clarity of the model dynamics crm use for interaction with crm form objects.

It’s not possible to interact with form objects using simple javascript in a supported way. Microsoft Dynamics CRM provides an object model of form elements that can be utilized to manipulate data, change form object properties, or analyze the current state of the form or data within the form. This object model is called Xrm.Page

Following is the Xrm.Page object’s hierarchy showing the available namespaces, objects, and their collections. You will be using these properties while writing JScript code:

Following are the things you can do with Xrm.Page model :

  • Change the appearance or manipulate form objects like data controls (text boxes, checkboxes, etc.), tabs, sections, etc.
  • Identify elements to show/hide.
  • Specify names of objects from which to retrieve/store data values.
  • Provide namespaces to properties so the system allows multiple controls per field or multiple forms per entity.

 Xrm.Page provides a namespace container for three objects described in the following table:

Namespaces

Object Description
context Provides methods to retrieve information specific to an organization, a user, or parameters that were passed to the form in a query string.
data Provides access to the entity data and methods to manage the data in the form as well as in the business process flow control
ui Contains methods to retrieve information about the user interface, in addition to collections for several sub components of the form.

Execution context
When you register a function for an event handler you have the option to pass an execution context object as the first parameter to the function as shown in below image. This object contains methods that allows you to manage variables you wish to share with other event handlers and the save event.

Below is the image how you pass execution context tothe javascript function

Xrm.Page.context

Following are some examples of common context methods:

1. getOrgUniqueName:

Returns the unique text value of the organization’s name.

 var OrgName= context.getContext().getOrgUniqueName();

2.getClientUrl: 

Returns the base server URL. When a user is working offline with Microsoft Dynamics CRM for Microsoft Office Outlook, the URL is to the local Microsoft Dynamics CRM Web services.

var serverUrl =  using Xrm.Page.context.getClientUrl().

3. getUserId:

Returns the guid value of the SystemUser.id value for the current user.

var userguid= context.getContext().getUserId();

4. getUserRoles:

Returns an array of strings representing the GUID values of each of the security roles that the user is associated with.

var currentUserRoles = Xrm.Page.context.getUserRoles();

Later on you can get the names of these security roles with one more api call.

Objects

1. Entity

Provides method to −

  • Retrieve record information
  • Save method
  • Collection attributes

2. Process

Methods to retrieve properties of the business process flow(BPF).

3. Navigation

Provides access to navigation items using items collection.

4. FormSelector

Uses Items collection to access available forms to the user. Also uses the navigation method to close and open forms.

5. Stages

Each process (BPF) has a collection of stages that can be accessed using getStages method of process.

6. Steps

Each stage comprises of various steps that can be accessed using getSteps method of stage.

Collections

1.Attributes

Provides access to entity attributes available on the form for getting any field value.

2. Controls

     ui.controls − Provides access to each control present on the form.

     attribute.controls − Provide access to all the controls within an attribute.

     section.controls − Provide access to all the controls within a section.

3.Items

      Provides access to all the navigation items on a form.

4. Tabs

     Provides access to all the tabs on a form.

5. Sections

     Provides access to all the sections on a form.

Events supported by form programming in crm

Javascript programming using Xrm.Page model allows you to handle the following form events :

  • onLoad (when form get loaded)
  • onSave  (when form/record is saved)
  • onChange (on change of any field value)
  • TabStateChange (Change of state of any tab on the form)
  • OnReadyStateComplete
  • PreSearch (On clicking on magnifier icon on lookup control )
  • Business Process Flow control events (events on BPF)

Example

Now we’ll discuss an example of javascript client side programming in dynamics crm.

We have a field named preferred method of communication on contact form in ms crm.

We want to make the email field mandatory if user select email, phone field mandatory if the user selects phone and so on. Except for the selected one, all the fields should get un-mandatory. If any is selected, all fields should get un-mandatory.

Below is the javascript for this requirement:

function Test()
{
    var PreferredMethodofContact = Xrm.Page.getAttribute("preferredcontactmethodcode").getValue(); 
    if (PreferredMethodofContact == 2)//email
   {
     Xrm.Page.getAttribute("emailaddress1").setRequiredLevel("required"); 
   }
  else if (PreferredMethodofContact == 3)//phone
  {
    Xrm.Page.getAttribute("mobilephone").setRequiredLevel("required"); 
   }
  else if (PreferredMethodofContact == 4)//fax
 {
   Xrm.Page.getAttribute("fax").setRequiredLevel("required"); 
  }
  else if (PreferredMethodofContact == 1)//any
  {
     Xrm.Page.getAttribute("emailaddress1").setRequiredLevel("none");
     Xrm.Page.getAttribute("mobilephone").setRequiredLevel("none"); 
     Xrm.Page.getAttribute("fax").setRequiredLevel("none"); 
    }
}

 

Now add the function in a javascript library ( new_Test2 in our case) and attach  function Test on change of Preferred method of contact field on contact entity
as shown below:

Click ok, save and publish.

Once published, let’s test by selecting different values of field Preferred method of communication:

× WhatsApp Chat with us