Understanding Xrm.Page Object Model

Xrm.Page Namespace

When writing form scripts, we will interact with objects from the Xrm.Page namespace to perform the following actions:

  1. Get/Set attribute values.
  2. Show/Hide user interface elements.
  3. Reference multiple controls per attribute.
  4. Access multiple forms per entity.
  5. Manipulate form navigation items.

 

Xrm.Page Object Hierarchy

Context – Provides methods to retrieve information specific to an organization, a user, or parameters that were passed to a form as a query string.

Data – Provides access to the entity data and methods to manage data in the form.

UI – Contains methods to retrieve information about the user interface, in addition to collections for several sub components of the form.
xrm.PageObjectModel

 

Execution Context

When you register a function for an event handler, CRM lets you pass the execution context object as the first parameter to the function.

This object contains methods that allow you to managed variables you wish to share with other event handlers.

 

Collections

attributes:

  1. 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 on the form are available.

 

controls:

  1. controls provides access to each control on the form.
  2. controls provide access to each control that have more than one control for an attribute available on the form.
  3. controls provides a collection of controls found in a section.

 

  1. items:
  2. Page.ui.navigation.items collection provides access to navigation items that are defined using the navigation area of the form editor.

 

  1. items:

If multiple forms are associated with an entity, each form can be associated with a security role and if security roles of a user enable users to see more than one form, they can select from a collection of Xrm.Page.ui.formSelector.items. A form definition is available in this case.

 

tabs:

  1. Page.ui.tabs provides access to collection of each of the tabs present on the form.

 

sections:

A tab can be organized by using more than one section. The tab sections collection provides access to these sections.

 

Hope this overview was helpful to you!

Fundamentals of JavaScript CRM Customization

JavaScript form customization is a way to interact with entity forms by using JavaScript that is executed for events that occur on the form.

JavaScript form customizations is one of many options to control business processes.

An advantage of JavaScript Form programming is that they are immediate and doesn’t need data to be submitted.

Frequent tasks performed by using form programming are:

  1. Data Validation.
  2. Automation.
  3. Process enhancement and enforcement.

 

USE FIELD AND FORM EVENTS

Scripts can be added on events like

OnLoad

OnSave

OnChange

Whereas, tabs have the event

TabStateChange

and IFRAMES have an event called

OnReadyStateComplete

 

EVENTS

OnLoad Event

OnLoad event occurs after the form has loaded. onLoad event is used to prepare the data in the form for use.

 

OnSave Event

OnSave event occurs when a form is saved. It does not correspond to standard HTML OnSubmit event. The OnSave event occurs in the following scenarios:

  1. When a user clicks on the save button at the bottom right corner of the screen.
  2. Code executes the Page.data.entity.save method, even when there is no changed data to be saved.
  3. The user navigates away from the page and there is unsaved data to be saved.
  4. When auto-save is enabled, 30 seconds after the data has been changed and there is unsaved data on the form.
  5. Code executes the Page.data.save and even if there is unsaved data on the form.
  6. Code executes the Page.data.refresh method passing true as the first parameter and there is unsaved data on the form.

 

OnChange Event

OnChange is available for every field. OnChange event requires  two conditions to be true:

  1. The data in the field must change.
  2. The field must lose focus.

There is an exception to the Two-Option (Boolean) fields. OnChange event occurs immediately when the value is changed without requiring to lose focus.

The OnChange event does not occur if the field is changed programmatically using the setValue method. Instead fireOnChange method can be used in code to trigger OnChange event.

 

TabStateChangeEvent Event

This event occurs when a tab is expanded or collapsed.

This event is important in the case that you want to use script to modify the src property of an IFRAME control.

 

OnReadyStateComplete Event

This event is fired when contents of an IFRAME have completed loading.

 

STEPS TO ADD JAVASCRIPT AS A WEB RESOURCE AND APPLY FORM CUSTOMIZATIONS

  • JavaScript files for form customization are applied as a Web Resource.
  • Navigate to Settings > Customizations > Customize the System. Then navigate to Web Resources under Components on the left navigation pane of the Default Solution (Default solution here is used as an example).

addWebResource

  • In order to add a JavaScript file, we need to create a new Web Resource.

newWebResource

A new JavaScript file could be uploaded or JavaScript code could be simply written in the Text Editor provided by CRM’s Web Resource.

  • So this way, a new Web Resource of type JavaScript could be created which then can be consumed on CRM Forms for customization purposes.
  • For registering events on OnLoad events, select Form Properties on the form.

formProperties

  • In Form Properties, Select the form libraries that we want to enable on the form level as shown below.

addEventHandler

In the above example, a library called ‘new_sampleScript’ has been included. We can now add Event Listeners (which are the functions in that library) that we want to trigger when the library is loaded.

 

handlerProperties

In the above dialog box, select the library which has the desired javascript file/code.

Enter the name of the function you want to trigger on this event.

 

As shown above, OnLoad events could be executed using JavaScript.

 

Similarly,

OnSave event listeners could be bound by simply changing the Event to OnSave as shown below.

changeEvent

For OnChange events, the Field Properties need to be changed. Steps to do so are as follows:

  1. Navigate to the desired field and select its properties.

fieldProperties

  1. Follow the steps as illustrated for OnSave and OnLoad events above.
  2. So JavaScript code registered OnChange will get triggered when the field value changes and when the field loses focus (Remember, data needn’t be saved for OnChange events to be fired).

Hope this is useful! 🙂