The control object provides methods to change the presentation or behavior of a control and identify the corresponding attribute.
We can access controls using the Xrm.Page.ui.controls, Xrm.Page.ui Section.controls, or Xrm.Page.data.entity Attribute.controls collections. The Xrm.Page.getControl method is a shortcut method to access Xrm.Page.ui.controls.get.
The new custom controls for CRM mobile clients (phones and tablets) supports all the control properties and methods except Auto-completion methods, getValue, Keypress methods and Lookup control methods and events.
Control properties and methods
Auto-completion methods
Configure the auto-completion experience in text controls in CRM forms. These are the methods which introduced in CRM 2016.
getValue
Gets the latest value for a control as users type a character in a specific text or number field. This method was introduced in CRM 2016.
Keypress methods
Add, remove, or perform a function when the user presses a key in a control. These methods were introduced in CRM 2016.
Auto-completion methods
We can use showAutoComplete and hideAutoComplete methods to configure the auto-completion experience in text controls in CRM forms.
showAutoComplete
We can use this method to show up to 10 matching strings in a drop-down list as users press keys to type character in a specific text field. We can also add a custom command with an icon at the bottom of the drop-down list.
JavaScript
Xrm.Page.getControl(arg).showAutoComplete(object)
Parameter
Type: Object that defines the result set, which includes results and commands, to be displayed in the auto-completion drop-down list.
Remarks: Call this method in a function that you added using the addOnKeyPress method to execute on the keypress event.
Example: The following example shows the definition of the object to be passed to the showAutoComplete method.
JavaScript
var resultset = {
results: [{
id: <value1>,
icon: <url>,
fields: [<fieldValue1>]},
{...},
{
id: <valueN>,
icon: <url>,
fields: [<fieldValue1, fieldValue2,..., fieldValueN>]}],
commands:{
id: <value>,
icon: <url>,
label: <value>,
action: <function reference>
}
}
hideAutoComplete
We can use this function to hide the auto-completion drop-down list we configured for a specific text field.
JavaScript
Xrm.Page.getControl(arg).hideAutoComplete()
getValue
This will give the latest value in a control as the user types characters in a specific text or number field. This method helps us to build interactive experiences by validating data and alerting users as they type characters in a control.
The getValue method is different from the attribute Xrm.Page.getAttribute(arg).getValue() method because the control method retrieves the value from the control as the user is typing in the control as opposed to the attribute Xrm.Page.getAttribute(arg).getValue() method that retrieves the value after the user commits (saves) the field.
For a sample JavaScript code that uses the getValue method to configure the auto-completion.
JavaScript
Xrm.Page.getControl(arg).getValue()
Return Value
Type: String. The latest data value for a control.
Keypress methods
We can use addOnKeyPress, removeOnKeyPress, and fireOnKeyPress methods to provide immediate feedback or take actions as user types in a control. These methods enable us to perform data validations in a control even before the user commits (saves) the value in a form.
addOnKeyPress
We can use this to add a function as an event handler for the keypress event so that the function is called when we type a character in the specific text or number field.
For a sample JavaScript code that uses the addOnKeyPress method to configure the auto-completion.
JavaScript
Xrm.Page.getControl(arg).addOnKeyPress([function reference])
Parameter
Type: function reference
Remarks: The function will be added to the bottom of the event handler pipeline. The execution context is automatically set to be passed as the first parameter passed to event handler set using this method.
We should use reference to a named function rather than an anonymous function if we want to remove the event handler for the field.
removeOnKeyPress
We can use this to remove an event handler for a text or number field that we have added using addOnKeyPress.
JavaScript
Xrm.Page.getControl(arg).removeOnKeyPress([function reference])
Parameter
Type: function reference
Remarks: If an anonymous function is set using addOnKeyPress, it can’t be removed using this method.
fireOnKeyPress
We can use this to manually fire an event handler that we created for a specific text or number field to be executed on the keypress event.
JavaScript
Xrm.Page.getControl(arg).fireOnKeyPress()