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.

Note

The formSelector items collection does not exist and the formSelector.getCurrentItem method does not work with Microsoft Dynamics CRM for tablets.

formSelector.getCurrentItem

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

Note

When only one form is available this method will return null.

  • Return Value
    Type: Object

formSelector.items

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

Note

Only those forms that share an association with one of the user’s security roles are available in this collection.

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.

Note

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

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.

A collection of all the navigation items on the page.

Note

This collection does not exist with Microsoft Dynamics CRM for tablets.

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.

Note

This method does not work with Microsoft Dynamics CRM for tablets.

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.

Note

These methods do not work with Microsoft Dynamics CRM for tablets.

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)