Xrm.Page.ui.controls Collection

  • Article

[Applies to: Microsoft Dynamics CRM 2011]

Xrm.Page.ui.controls is a collection of all the controls present on the page. This collection provides methods to retrieve or perform actions on each of the controls on the page.

Examples shown are in the Sample: SDK.UISamples.js library.

Note

You can also access a controls collection through an attribute or a section. Each controls collection implements the same methods except the controls available are limited to those within the parent.

Methods

The following table lists the methods of Xrm.Page.ui.controls.

Method Description

forEach

Applies the action contained within a delegate function.

get

Returns one or more controls depending on the arguments passed.

getLength

Returns the number of controls in the collection.

forEach

Applies the action contained within a delegate function.

Xrm.Page.ui.controls.forEach(delegate function(control, index))
  • Arguments
    Delegate function with parameters for control and index.

Example: The SDK.UISamples.getMultipleControlAttributes function alerts the user of any attributes that have multiple controls on the form.

SDK.UISamples.getMultipleControlAttributes = function () {
 var attributesOnForm = [];
 var multipleControlAttributes = [];

 Xrm.Page.ui.controls.forEach(function (control, index) {
  if (SDK.UISamples.doesControlHaveAttribute(control)) {
   var attribute = control.getAttribute();
   if (attribute != null) {
    var attributeName = attribute.getName();

    // Check if the attribute has already been added to the attributesOnForm collection
    if (SDK.UISamples.arrayContainsValue(attributesOnForm, attributeName)) {
     // Check if the attribute has already been added to the
     // multipleControlAttributes collection.  This would happen
     // if an attribute has 3+ controls on the form.
     if (SDK.UISamples.arrayContainsValue(multipleControlAttributes, attributeName) == false) {
      multipleControlAttributes.push(attributeName);
     }
    }
    else {
     attributesOnForm.push(attributeName);
    }
   }
  }
 });


 var message = "";
 if (multipleControlAttributes.length > 0) {
  message = "The following attributes have multiple controls on the form:\n\n- ";
  message += multipleControlAttributes.join("\n- ");
 }
 else {
  message = "There are no attributes on the form with multiple controls";
 }

 alert(message);
};

SDK.UISamples.doesControlHaveAttribute = function (control) {
 var controlType = control.getControlType();
 return controlType != "iframe" && controlType != "webresource" && controlType != "subgrid";
};

SDK.UISamples.arrayContainsValue = function (array, value) {
 for (var i in array) {
  if (array[i] == value)
   return true;
 }

 return false;
};

Methods

get

Returns one or more controls depending on the arguments passed.

Xrm.Page.ui.controls.get([String][Number][delegate function(attribute, index)])

Tip

You can use the Xrm.Page.getControl() shortcut to access this method directly.

  • Arguments

    • None

      • Return Value All the controls.
        Type: Array

        Example: The SDK.UISamples.getFirstControlAttribute function alerts the user with the attribute label of the first control on the form.

    • String

      • Return Value The control where the name matches the argument.
        Type: Object

        Note

        Any additional controls for any attribute will be named <attribute name>+n. For example, if there are two controls for an attribute named “new_regionoptionset” the first control will be named “new_regionoptionset” and the second will be named “new_regionoptionset1”.

    • Number

      • Return Value The control where the index matches the number
        Type: Object

        Example: The SDK.UISamples.getFirstControl function gets the first control on the form, and then using the attribute name from the control, gets the control by name, and compares the two.

        SDK.UISamples.getFirstControl = function () {
 var firstControlByPosition = Xrm.Page.ui.controls.get(0);
 var firstControlByName = Xrm.Page.ui.controls.get(firstControlByPosition.getName());

 if (firstControlByName == firstControlByPosition) {
  alert("The first control on the form is '" + firstControlByPosition.getLabel() + "'.");
 }
 else {
  alert("An error has occurred:\n\nUnable to determine the label of the first control on the form.");
 }

};

    • delegate function(attribute, index)

      • Return Value Any controls that cause the delegate function to return true.
        Type: Array

        Example: The SDK.UISamples.getAllLookupAttributes function alerts the user with the attribute name for every lookup control on the form.

        SDK.UISamples.getAllLookupAttributes = function () {
 var message = "The following lookup attributes are on the form:\n\n";

 var lookupControls = Xrm.Page.ui.controls.get(SDK.UISamples.isLookup);
 for (var i in lookupControls) {
  message += "- " + lookupControls[i].getLabel() + "\n";
 }

 alert(message);
};

SDK.UISamples.isLookup = function (control, index) {
 return control.getControlType() == "lookup";
};

Methods

getLength

Returns the number of controls in the collection.

Xrm.Page.ui.controls.getLength()

  • Return Value
    Type: Number

    Example: The SDK.UISamples.getControlCount function alerts the user of how many controls are on the current form.

    SDK.UISamples.getControlCount = function () {
 var controlsLength = Xrm.Page.ui.controls.getLength();

 alert("This form has " + controlsLength + " controls on it.");
};

Methods

See Also

Tasks

Sample: SDK.UISamples.js

Reference

Xrm.Page.ui

Concepts

Form Scripting Quick Reference
Write Code for Microsoft Dynamics CRM Forms
Use the Xrm.Page Object Model

Microsoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.