Export (0) Print
Expand All

Use the Xrm.Page object model

Applies To: Microsoft Dynamics CRM 2013, Microsoft Dynamics CRM Online

When you write form scripts you will interact with objects in the Xrm.Page namespace to perform the following actions:

  • Get or set attribute values.

  • Show and hide user interface elements.

  • Reference multiple controls per attribute.

  • Access multiple forms per entity.

  • Manipulate form navigation items.

For more examples, see Form scripting quick reference.

ImportantImportant
Microsoft Dynamics CRM 4.0 used the crmForm object to provide access to form fields. The crmForm object was deprecated in Microsoft Dynamics CRM 2011. The crmForm object is not available in Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online.

Xrm.Page object hierarchy

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

 

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.

ui

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

Xrm.Page object model

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. This object contains methods that allows you to manage variables you wish to share with other event handlers and the save event. For more information, see Execution context (client-side reference) and Save event arguments (client-side reference).

Collections

The following table describes the Xrm.Page object model collections. See Collections (client-side reference) for information about the methods available for collections.

 

Collection Description

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 defined using the navigation area of the form editor. With Updated forms forms, people navigate to these using the command bar. In Classic forms these are 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.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 sections collection provides access to each of these sections.

Object descriptions

Each object possesses several methods to retrieve data, get or set object properties, or perform actions:

attribute

Each attribute corresponds to an entity attribute that has been added to the form as a field. Generally only those entity attributes that have been added to the form as a field are available. Each instance of a field is a control. A field can be added to a form more than one time, which creates multiple controls that refer to the same attribute.

noteNote
Composite attributes have special behaviors. More information: Write scripts for composite attributes

Attributes are categorized by type. You can determine the type of an attribute by using the getAttributeType method.

While all attributes share some common methods, certain methods are only available for specific attribute types. For more information, see Xrm.Page.data.entity attribute (client-side reference).

noteNote
Attribute type information represents the behavior of the attribute in the form. It does not necessarily correspond to the field type defined in the application or the AttributeMetadata types. Attributes of a particular field type may behave differently depending on how they are formatted.

The following table lists the attribute type string values to expect for each type of attribute schema type and format option.

 

Application Field Type Format Option Attribute Type

Currency

NA

money

Date and Time

Date and Time, Date Only

datetime

Decimal Number

NA

decimal

Floating Point Number

NA

double

Lookup

NA

lookup

Multiple Lines of Text

NA

memo

Option Set

NA

optionset

Single Line of Text

E-mail, Text, Ticker Symbol, Url, Phone

string

Single Line of Text

Text Area

memo

Status

NA

optionset

Status Reason

NA

optionset

Two Options

Two Radio Buttons, Checkbox, List

boolean

Whole Number

None, Duration

integer

Whole Number

Language, Time Zone

optionset

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. For more information, see Client-side context (client-side reference).

control

Represents an HTML element present on the form. Some controls are bound to a specific attribute, whereas others may represent unbound controls such as an IFRAME, Web resource, or a sub grid that has been added to the form.

Use specific control names in your code for IFrame, Web Resource, and Subgrid controls. These controls are not bound to an attribute. Avoid including specific control names in your code when the control is bound to an attribute. When multiple controls are bound to an attribute, the control names are determined at runtime and can vary depending on where the control is located in the form.

For most tasks related to attribute bound controls, you will access the controls by using the attribute controls collection or through the controls collection of a section. Rather than refer to a control by name, you will gain a reference to it based on the context of the collection. In this case, the name is not important. See the example found for the attribute Controls Collection for a way to create functions to perform actions across all the controls that are bound to a specific attribute.

noteNote
Composite attributes have special behaviors. More information: Write scripts for composite attributes.

noteNote
For most script development work outside of Microsoft Dynamics CRM, developers may be accustomed to referring to page elements by using the document.getElementById method. For Microsoft Dynamics CRM form scripts this method is not supported. It is important to recognize that the attribute stores the data and the control is simply the presentation of the attribute in the form. For controls bound to attributes you may need to adjust the way you are accustomed to accessing data in the form.

Controls are categorized by type. You can determine the type of a control by using the getControlType method. Certain control methods are only available for specific types of controls. For example, the addOption method is only available for controls that are presented as option sets. For more information, see Xrm.Page.ui control (client-side reference).

entity

Xrm.Page.data.entity provides methods to retrieve information specific to the record displayed on the page, the save method, and a collection of all the attributes included in the form. See Xrm.Page.data.entity (client-side reference) for more information.

navigation

Does not contain any methods. Provides access to navigation items through the items collection.

formSelector

The Xrm.Page.ui.formSelector contains an items collection that provides capabilities to query the forms available for the current user. Use the navigate method to close the current form and open a different one. For more information, see Xrm.Page.ui.formSelector item (client-side reference).

tab

A tab is a group of sections on a page. It contains methods to change the presentation of the tab. You will access sections in the tab through the sections collection. For more information, see Xrm.Page.ui tab (client-side reference).

section

A section contains methods to manage how it appears in addition to accessing the tab that contains the section. A section also provides access to the controls within it through a controls collection. More information: Xrm.Page.ui section (client-side reference)

See Also

Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online
Send comments about this topic to Microsoft.
© 2014 Microsoft Corporation. All rights reserved.
Show:
© 2014 Microsoft