CRM Javascript Model

In this section of The CRM Book, we’ll go over the JavaScript CRM model. Microsoft Dynamics CRM uses the XRM Page Hierarchy JavaScript model as displayed below.

Prior to the introduction of this model in Dynamics CRM 2011, Microsoft Dynamics CRM 4.0 used the crmForm object to provide access to form fields. The crmForm object is deprecated in Microsoft Dynamics CRM 2011. Scripts that use the crmForm object will continue to work in Microsoft Dynamics CRM 2011 to support backward compatibility, but the new capabilities in Microsoft Dynamics CRM cannot be achieved by using the crmForm object. Please refer to the section of the book on JavaScript best practices for more information on this topic.

The Xrm.Page object serves as a namespace object to consolidate three objects on the form:

• Xrm.Page.context:  Xrm.Page.context provides methods to retrieve information specific to an organization, a user, or parameters that were passed to the form in a query string.
• Xrm.Page.data.entity: Xrm.Page.data provides an entity object that provides collections and methods to manage data within the entity form.
• Xrm.Page.ui: Xrm.Page.ui provides collections and methods to manage the user interface of the form.

Collections

Below are the Xrm.Page object model collections.

• Attributes: The Xrm.Page.data.entity.attributes Collection provides access to each entity attribute that is available on the form. Only those attributes that correspond to fields added to the form are available.
• Controls: Three objects contain a controls collection:
  • ui.controls:  The Xrm.Page.ui.controls Collection provides access to each control present on the form.
  • attribute.controls: Because an attribute may have more than one control on the form, this collection provides access to each of them. This collection will contain only one item unless multiple controls for the attribute are added to the form.
  • section.controls: This collection only contains the controls found in the section.
• Navigation.items:  The Xrm.Page.ui.navigation.items Collection provides access to navigation items that are visible on the left side of the form.
• FormSelector.items:  When multiple forms are provided for an entity, you can associate each form with security roles. When the security roles associated with a user enable them to see more than one form, the Xrm.Page.ui.formSelector.Xrm.Page.ui.formSelector.items Collection provides access to each form definition available to that user.
• Tabs: You can organize each form by using one or more tabs. The Xrm.Page.ui.tabs Collection provides access to each of these tabs.
• Sections: You can organize each form tab by using one or more sections. The tab Xrm.Page.ui tab.sections Collection provides access to each of these sections.

Each object possesses several methods to retrieve data, get or set object properties, or perform actions. Generally speaking for majority of use cases a subset of methods utilizing these model hierarchy is utilized.  Given below are examples of some common methods that utilize the methods in this model.

Xrm.Page.context

Xrm.Page.context provides methods to retrieve information specific to an organization, a user, or parameters that were passed to the form in a query string. Some of the common methods used are:

• getOrgUniqueName: Returns the unique text value of the organizations name.
  • var OrganizationUniqueName = context.getContext().getOrgUniqueName();
• 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.
• getUserId: Returns the GUID value of the SystemUser.id value for the current user.
  • var userGUID = context.getContext().getUserId();
• 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();

Xrm.Page.data.entity

The Xrm.Page.data.entity Attribute Methods are frequently used to get and set propertied of various attributes on the form.  Few examples of the methods commonly used are:

• Get the value from a CRM field
  • var varMyValue = Xrm.Page.getAttribute(“CRMFieldSchemaName”).getValue() ;
• Set the value of a CRM field
  • Xrm.Page.getAttribute(“po_CRMFieldSchemaName”).setValue(‘My New Value’);
• Get the selected value of an optionset
  • Xrm.Page.getAttribute(“CRMFieldSchemaName”).getSelectedOption().text;
• Set the requirement level
  • Xrm.Page.getAttribute(“CRMFieldSchemaName”).setRequiredLevel(“none”);
  • Xrm.Page.getAttribute(“CRMFieldSchemaName”).setRequiredLevel(“required”);
  • Xrm.Page.getAttribute(“CRMFieldSchemaName”).setRequiredLevel(“recommended”);

Xrm.Page.ui

Xrm.Page.ui contains methods to retrieve information about the user interface as well as collections for several subcomponents of the form. Xrm.Page.ui provides access to the following collections:

• Xrm.Page.ui.controls Collection: A collection of all the controls on the page. Given below are examples of common methods used in this collction:
  • Xrm.Page.ui.controls.get(“po_assignedtoteam”).setVisible(true); // Sets the field “po_assignedtoteam” to visible on the form
  • Xrm.Page.ui.controls.get(“po_assignedtoteam”).setDisabled(true); // Disables the field “po_assignedtoteam” on the form
• Xrm.Page.ui.navigation.items Collection: Xrm.Page.ui.navigation.items does not contain any methods. Provides access to navigation items through the items collection
• Xrm.Page.ui.formSelector: A common method used in this collection is the method to get the type of form currently in use as the example below illustrates:
  function checkFormType() {
  var formType = Xrm.Page.ui.getFormType();
  if (formType == 2) {
  // Code to execute some logic
  }
  }
• Xrm.Page.ui.tabs Collection: A collection of all the tabs on the page. Some of most common examples are to use methods in this collection to hide/unhide tabs and sections within a tab. Here are few examples:
  • Xrm.Page.ui.tabs.get(“Financial Services”).setVisible(false);  // Hides the “Financial Service” tab
  • Xrm.Page.ui.tabs.get(“Territory-Info”).sections.get(“TerritoryChangeType”).setVisible(true); // Sets the section “TerritoryChangeType” to visible