Use the Xrm.Page object model

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, 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.

• Interact with the business process flow control.

For more examples, see Form scripting quick reference.

In This Topic

Xrm.Page object hierarchy

Execution context

Collections

Object descriptions

• attribute

• context

• control

• entity

• formSelector

• navigation

• process

• section

• stage

• step

• tab

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 as well as in the business process flow control
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 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 TechNet: Updated forms, people navigate to these using the command bar. In TechNet: Classic formsthese 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.

Business process flow collections

Collections for stages and steps within Xrm.Page.data.process are based on the same collection structure but also allow for adding or removing items from the collections.

Use the process.getStages method to access the collection of stages. Use the stage.getSteps method to access the collection of steps.

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.

Note

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

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, 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 for a way to create functions to perform actions across all the controls that are bound to a specific attribute.

Note

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

Note

For most script development work outside of Microsoft Dynamics 365, developers may be accustomed to referring to page elements by using the document.getElementById method. For Microsoft Dynamics 365 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.

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

navigation

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

process

Contains methods to retrieve properties of a business process flow. More information: Process 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. More information: Xrm.Page.ui section (client-side reference)

stage

Each process has a collection of stages that can be access using the process getStages method.

One stage is the active stage. More information: Structure of business process flows

step

Steps represent individual items of data to be collected during a stage. Each stage has a collection of steps that can be accessed using the stage getSteps method. More information: Structure of business process flows

You can access a step control within the active stage of a business process flow control by referencing the control name with the special prefix “header_process_<control name>”. For example, to hide the step that represents the purchaseprocess attribute, use the following:

Xrm.Page.getControl("header_process_purchaseprocess").setVisible(false);

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

See Also

Form scripting quick reference
Write and debug scripts for Dynamics 365 for phones and tablets
Write code for Microsoft Dynamics 365 forms
Write scripts for composite attributes
Write scripts for business process flows
Use JavaScript with Microsoft Dynamics 365
Client-side programming reference
Client-side programming reference
JavaScript libraries for Microsoft Dynamics 365
Customize entity forms

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright