Export (0) Print
Expand All

Xrm.Page.ui.controls Collection

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

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

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)])
TipTip
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

noteNote
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

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

Community Additions

Show:
© 2014 Microsoft