Client API form context

Applies to Dynamics 365 for Customer Engagement apps version 9.x

The Client API form context (formContext) provides a reference to the form or to an item on the form, such as, a quick view control or a row in an editable grid, against which the current code is executed.

Earlier, the global Xrm.Page object was used to represent a form or an item on the form. With Dynamics 365 for Customer Engagement apps version 9.0, the Xrm.Page object is deprecated, and you should use the getFormContext method of the passed in execution context object to return reference to the appropriate form or an item on the form.

Important

Deprecated means that we intend to remove a feature or capability from a future major release of Dynamics 365 for Customer Engagement apps; the feature or capability will continue to work and is fully supported until it is officially removed.

Use of the Xrm.Page object as a static access to the primary form context is still supported to maintain backward compatibility with the existing scripts, and won’t be removed as soon as some other client API methods listed in the Client API deprecation section. We recommend that you use the new formContext object instead of the Xrm.Page object in your code targeting version 9.0 or later where possible. Also, using the formContext object enables you to create common event handlers that can operate either on a form or in an editable grid depending on where its called. More information: getFormContext (Client API reference).

Getting the formContext object for JavaScript functions for ribbon actions is different from how you get it in form scripting. More information: Form and grid context in ribbon actions.

Using the formContext object instead of the Xrm.Page object

It's easy to convert existing code with Xrm.Page to use the new formContext object. For example, consider the following script that uses the Xrm.Page object:

function displayName()
{
    var firstName = Xrm.Page.getAttribute("firstname").getValue();
    var lastName = Xrm.Page.getAttribute("lastname").getValue();
    console.log(firstName + " " + lastName);
}

Here is the updated script that uses the passed in execution context to retrieve the formContext object instead of using the static Xrm.Page object:

function displayName(executionContext)
{
    var formContext = executionContext.getFormContext(); // get formContext

    // use formContext instead of Xrm.Page  
    var firstName = formContext.getAttribute("firstname").getValue(); 
    var lastName = formContext.getAttribute("lastname").getValue();
    console.log(firstName + " " + lastName);
}

Important

You must remember to select the Pass execution context as first parameter option in the Handler Properties dialog while defining your event handlers to use the formContext object. More information: Client API execution context

formContext object model

Use the data and ui objects under the formContext object to programmatically manipulate data and user interface elements in Customer Engagement.

formContext object model

data object

Provides access to the entity data and methods to manage the data in the form as well as in the business process flow control. Contains the following objects:

Object Description
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 on the form
process Provides methods to retrieve properties of a business process flow.

It also provides an attributes collection for accessing non-entity bound control. See the Collections in the formContext object model section later in this topic.

More information: formContext.data

ui object

Provides methods to retrieve information about the user interface, in addition to collections for several sub components of the form or grid. Contains the following objects:

Object Description
formSelector Provides 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.
navigation Does not contain any methods. Provides access to navigation items through the items collection. See the next section on collections for more information.
process Provides methods to interact with the business process flow control on a form.

More information: formContext.ui

Collections in the formContext object model

The following table describes the collections in Xrm object model. For information about the methods available for collections in general, see Collections (Client API reference).

Collection Description
attributes Two objects contain an attributes collection:

- formContext.data.attributes collection provides access to non-entity bound attributes.

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

- formContext.ui.controls: Provides access to each control present on the form.

- formContext.data.entity.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.

- formContext.ui.tabs.sections.controls: This collection only contains the controls found in the section.
formContext.data.process.stages and formContext.data.process.steps Provides access to stages and steps collection in a business process flow. These also allow for adding and removing of items from the collection.
formContext.ui.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 formContext.ui.formSelector.items collection provides access to each form definition available to that user.
formContext.ui.navigation.items The formContext.ui.navigation.items collection provides access to navigation items that are defined using the navigation area of the form editor. People navigate to these using the command bar.
formContext.ui.quickForms Provides methods to access all the quick view controls and its constituent controls on the Customer Enagagement forms.
formContext.ui.tabs You can organize each form by using one or more tabs. This collection provides access to each of these tabs.
formContext.ui.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.

getFormContext method

getGlobalContext method

Execution context methods