Xrm.Page.ui (client-side reference)

Applies To: Dynamics CRM 2013

Xrm.Page.ui contains properties and methods to retrieve information about the user interface as well as collections for several subcomponents of the form.

Xrm.Page.ui Properties and Methods

• close
  Method to close the form.

• controls
  A collection of all the controls on the page.

• formSelector
  Use the formSelector.getCurrentItem method to retrieve information about the form currently in use and the formSelector.items collection containing information about all the forms available for the user.

• getCurrentControl
  Method to get the control object that currently has focus on the form.

  Note

  This method is deprecated in Microsoft Dynamics CRM 2013 Update Rollup 2.

• getFormType
  Method to get the form context for the record.

• navigation.items
  A collection of all the navigation items on the page.

• Form Notification
  Use setFormNotification to display form level notifications and clearFormNotification to remove notifications.

• refreshRibbon
  Method to cause the ribbon to re-evaluate data that controls what is displayed in it.

• tabs
  A collection of all the tabs on the page.

• ViewPort Methods
  The ViewPort is the area of the page containing form data. It corresponds to the body of the form and does not include the navigation, header, footer or form assistant areas of the page. Use the getViewPortHeight and getViewPortWidth methods to get the current size of the ViewPort.

close

Method to close the form.

Xrm.Page.ui.close()

Remarks:

The HTML Window.close method is suppressed. To close a form window you must use this method. If there are any unsaved changes in the form the user will be prompted whether they want to save their changes before the window closes.

With Microsoft Dynamics CRM for tablets this method mimics the behavior of the back navigation button.

controls

A collection of all the controls on the page.

See Collections (client-side reference) for information about the collection methods and Xrm.Page.ui control (client-side reference) for information about the control objects in the collection.

formSelector

Use the formSelector.getCurrentItem method to retrieve information about the form currently in use and the formSelector.items collection containing information about all the forms available for the user.

formSelector.getCurrentItem

Method to return a reference to the form currently being shown.

• Return Value
  Type: Object

formSelector.items

A collection of all the form items accessible to the current user.

See Collections (client-side reference) for information about the collection methods and Xrm.Page.ui.formSelector item (client-side reference) for information about the items in the collection.

getCurrentControl

Method to get the control object that currently has focus on the form. Web Resource and IFRAME controls are not returned by this method.

This method doesn’t return a reference to the current control when the last field edited by the user was a Boolean attribute formatted as a radio button or check box control. This method also fails to return a reference immediately after using the Xrm.Page.ui control setFocus method.

Xrm.Page.ui.getCurrentControl()

• Return Value
  Type: Object

getFormType

Method to get the form context for the record.

Xrm.Page.ui.getFormType()

• Return Value
  Type: Number

  The following table lists the form types that correspond to the return value.

  Value	Form Type
  0	Undefined
  1	Create
  2	Update
  3	Read Only
  4	Disabled
  5	Quick Create (Deprecated)
  6	Bulk Edit
  11	Read Optimized (Deprecated)

  Note

  Quick Create forms return 1. The value 5 was used for an earlier type of quick create form that was removed.

navigation.items

A collection of all the navigation items on the page.

See Collections (client-side reference) for information about the collection methods and Xrm.Page.ui.navigation item (client-side reference) for information about the items in the collection.

Form Notification

Use setFormNotification to display form level notifications and clearFormNotification to remove notifications.

clearFormNotification

Use this method to remove form level notifications.

Xrm.Page.ui.clearFormNotification(uniqueId)

• Parameters

  • uniqueId
    Type: String. A unique identifier for the message used with setFormNotification to set the notification.

• Return Value
  Type: Boolean. True if the method succeeded, otherwise false.

• Remarks
  This method is only available for Updated entities.

setFormNotification

Use this method to display form level notifications. You can display any number of notifications and they will be displayed until they are removed using clearFormNotification. The height of the notification area is limited so each new message will be added to the top. Users can scroll down to view older messages that have not yet been removed.

Xrm.Page.ui.setFormNotification(message, level, uniqueId);

• Parameters

  • message
    Type: String. The text of the message

  • level
    Type: String. The level of the message.

    The level defines how the message will be displayed.

    • ERROR : Notification will use the system error icon.

    • WARNING : Notification will use the system warning icon.

    • INFO : Notification will use the system info icon.

  • uniqueId
    Type: String. A unique identifier for the message used with clearFormNotification to remove the notification.

• Return Value
  Type: Boolean. True if the method succeeded, otherwise false.

• Remarks
  This method is only available for Updated entities.

refreshRibbon

Method to cause the ribbon to re-evaluate data that controls what is displayed in it.

Xrm.Page.ui.refreshRibbon()

• Return Value
  Type: None

  Remarks: This function is typically used when a ribbon <EnableRule> (RibbonDiffXml) depends on a value in the form. After your code changes a value that is used by a rule, use this method to force the ribbon to re-evaluate the data in the form so that the rule can be applied.

tabs

A collection of all the tabs on the page.

See Collections (client-side reference) for information about the collection methods and Xrm.Page.ui tab (client-side reference) for information about the items in the collection.

ViewPort Methods

The ViewPort is the area of the page containing form data. It corresponds to the body of the form and does not include the navigation, header, footer or form assistant areas of the page. Use the getViewPortHeight and getViewPortWidth methods to get the current size of the ViewPort.

getViewPortHeight

Method to get the height of the viewport in pixels.

Xrm.Page.ui.getViewPortHeight()

• Return Value
  Type: Number

getViewPortWidth

Method to get the width of the viewport in pixels.

Xrm.Page.ui.getViewPortWidth()

• Return Value
  Type: Number

See Also

Client-side programming reference
Form scripting quick reference
Write code for Microsoft Dynamics CRM 2013 forms
Use the Xrm.Page object model
Xrm.Page.data.entity (client-side reference)