Use the Xrm.Page Object Model
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.
Important |
|---|
| 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. |
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:
|
|
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:
|
|
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.
Note |
|---|
| 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.
Note |
|---|
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
Reference
Xrm.Page ReferenceConcepts
Form Scripting Quick ReferenceUse JavaScript with Microsoft Dynamics CRM
Sample: Create Dependent OptionSets (Picklists)
JScript Libraries for Microsoft Dynamics CRM
Customize Entity Forms
Other Resources
Xrm.Page Sample LibrariesClient-Side Programming Reference
Microsoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.
Important