Export (0) Print
Expand All

Use the Xrm.Page Object Model

[Applies to: Microsoft Dynamics CRM 2011]

Microsoft Dynamics CRM 2011 introduces a new object model for form programming. This new object model provides the following additional capabilities:

  • Show and hide user interface elements.

  • Support multiple controls per attribute.

  • Support multiple forms per entity.

  • Manipulate form navigation items.

ImportantImportant
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.

In This Topic

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. The data object does not have any methods; it provides namespace separation to the entity data to provide for expansion in future versions of Microsoft Dynamics CRM.

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 managed variables you wish to share with other event handlers and the save event. For more information, see Form Event Handler Execution Context Reference and Save Event Arguments Reference.

Collections

The following table describes the Xrm.Page object model 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 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.

Collection Methods

The following table describes the three methods each collection implements.

 

Method Description

forEach

Accepts a delegate function to apply action on each item of the collection.

get

Accepts four different parameters that control what is returned:

None
When no arguments are passed, the get method returns all items in the collection.

String
When a string is passed, the get method returns the item where the name of the item matches the string.

Number
When a number is passed, the get method returns the item where the index position in the collection matches the number.

delegate function
When a delegate function is passed, the get method returns any items that cause the delegate function to return a Boolean value of true.

getLength

Returns the number of items in the collection.

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. 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.

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 Methods.

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

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 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.

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 Methods.

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.

navigation

Does not contain any methods. Provides access to navigation items through the items collection. For more information, see Xrm.Page.ui.navigation.items Collection.

formSelector

The Xrm.Page.ui.formSelector contains an Xrm.Page.ui.formSelector.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 methods.

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 methods.

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. For more information, see Xrm.Page.ui tab Section Methods and Controls Collection.

See Also

Microsoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.

Community Additions

ADD
Show:
© 2014 Microsoft