SOURCE : msdn.microsoft.com
Xrm.Page.ui control (client-side reference)
Dynamics CRM 2013
This topic has not yet been rated – Rate this topic
Applies To: Microsoft Dynamics CRM 2013, Microsoft Dynamics CRM Online
The control object provides methods to change the presentation or behavior of a control and identify the corresponding attribute.
You access controls using the following collections: Xrm.Page.ui.controls, Xrm.Page.ui Section.controls, or Xrm.Page.data.entity Attribute.controls. TheXrm.Page.getControl method is a shortcut method to access Xrm.Page.ui.controls.get.
Each of the syntax examples in this topic show the use of the Xrm.Page.getControl method to access a control. Which control depends on the arguments passed to the method. The args parameter to access a single control must be either the name of the control or the index.
When a form displays a business process flow control in the header, additional controls will be added for each attribute that is displayed in the business process flow. These controls have a unique name like the following:
header_process_<attribute name>.Controls displayed in the form header are accessible and have a unique name like the following:
header_<attribute name>.For controls that are bound to attributes it is common to access controls through the Xrm.Page.data.entity Attribute.controls collection
- Disabled
- Detect the state and enable or disable controls using the getDisabled and setDisabled methods.
- getAttribute
- Get the attribute that the control is bound to.
- getControlType
- Get information about the type of control.
- getName
- Get the name of the control
- getParent
- Get the section object that the control is in.
- Lookup control methods and events
- Control the results displayed for a user to choose from when they set the value of a lookup control using the addCustomFilter, addCustomView, getDefaultView,setDefaultView methods.
You can add or remove event handlers for the PreSearch event using the addPreSearch and removePreSearch methods.
- Notification
- Display and remove notifications to users about a control using the setNotification and clearNotification methods.
- OptionSet control methods
- Modify the options displayed in OptionSet controls using the addOption, clearOptions, and removeOption methods.
- refresh
- Refresh the data displayed in a subgrid.
- setFocus
- Set focus on a control.
- setShowTime
- Specify whether a date control should show the time portion of the date.
- Visible
- Determine which controls are visible and show or hide them using the getVisible and setVisible methods.
- Web resource and IFRAME control methods
- Interact with web resource and IFRAME controls using the getData, setData, getInitialUrl, getObject, setSrc and getSrc methods.
Use getDisabled and setDisabled to detect whether a control is disabled or to enable or disable it.
Control Types: standard, lookup, optionset.
getDisabled
Returns whether the control is disabled.
Xrm.Page.getControl(arg).getDisabled()
- Return Value
- Type: Boolean. True if the control is disabled, otherwise false.
setDisabled
Sets whether the control is disabled.
Xrm.Page.getControl(arg).setDisabled(bool)
- Arguments
- Type: Boolean. True if the control should be disabled, otherwise false.
Returns the attribute that the control is bound to.
Control Types: standard, lookup, optionset.
Xrm.Page.getControl(arg).getAttribute()
 Note |
|---|
| Controls that are not bound to an attribute (subgrid, web resource, and IFRAME) do not have this method. An error will be thrown if you attempt to use this method on one of these controls. |
- Return Value
- Type: Object: An attribute.
Remarks
The constituent controls within a quick view control are included in the controls collection and these controls have the getAttribute method. However, the attribute is not part of the attribute collection for the entity. While you can retrieve the value for that attribute using getValue and even change the value using setValue, changes you make will not be saved with the entity.
The following code shows using the value the contact mobilephone attribute when displayed on an account entity form using a quick view control namedcontactQuickForm. This code will hide the control when the value of the attribute is null.
var quickViewMobilePhoneControl = Xrm.Page.getControl("contactQuickForm_contactQuickForm_contact_mobilephone"); if (quickViewMobilePhoneControl.getAttribute().getValue() == null) { quickViewMobilePhoneControl.setVisible(false); }
Returns a value that categorizes controls.
Control Types: all.
Xrm.Page.getControl(arg).getControlType()
- Return Value
- Type: String
Possible return values of getControlType:
Return Value Description standardA Standard control.iframeAn IFRAME controllookupA Lookup control.optionsetAn OptionSet controlsubgridA subgrid controlwebresourceA web resource controlnotesA Notes control
Returns the name assigned to the control.
| Note |
|---|
| The name assigned to a control is not determined until the form loads. Changes to the form may change the name assigned to a given control. |
Control Types: all.
Xrm.Page.getControl(arg).getName()
- Return Value
- Type: String. The name of the control.
Returns a reference to the section object that contains the control.
Control Types: all.
Xrm.Page.getControl(arg).getParent()
- Return Value
- Type: Xrm.Page.ui section (client-side reference) object.
Control Types: all.
getLabel
Returns the label for the control
Xrm.Page.getControl(arg).getLabel()
- Return Value
- Type: String. The label of the control.
setLabel
Sets the label for the control.
Xrm.Page.getControl(arg).setLabel(label)
- Arguments
- Type: String. The new label for the control.
Control the results displayed for a user to choose from when they set the value of a lookup control using the addCustomFilter, addCustomView, getDefaultView,setDefaultView methods. The Lookup control also exposes the PreSearch event so that you can programmatically add event handlers using the addPreSearch andremovePreSearch methods.
Control Types: lookup.
addCustomFilter
Use add additional filters to the results displayed in the lookup. Each filter will be combined with any previously added filters as an ‘AND’ condition.
Xrm.Page.getControl(arg).addCustomFilter(filter, entityLogicaName)
- Arguments
-
- filterXml
- Type: String: The fetchXml filter element to apply. For example:
<filter type="and"> <condition attribute="address1_city" operator="eq" value="Redmond" /> </filter>
- entityLogicalName
- Type: String: (Optional) If this is set the filter will only apply to that entity type. Otherwise it will apply to all types of entities returned.
- Remarks
- More information: FetchXML schema.
This method is only available for Updated Entities.
This method can only be used in a function in an event handler for the Lookup Control PreSearch Event.
addCustomView
Adds a new view for the lookup dialog box.
Xrm.Page.getControl(arg).addCustomView(viewId, entityName, viewDisplayName, fetchXml, layoutXml, isDefault)
- Arguments
-
- viewId
- Type:String: The string representation of a GUID for a view.
Note
This value is never saved and only needs to be unique among the other available views for the lookup. A string for a non-valid GUID will work, for example “{00000000-0000-0000-0000-000000000001}”. It is recommended that you use a tool like guidgen.exe to generate a valid GUID. The guidgen.exe tool is included in the Windows SDK.
- entityName
- Type: String: The name of the entity.
- viewDisplayName
- Type: String: The name of the view.
- fetchXml
- String: The fetchXml query for the view.
- layoutXml
- Type:String: The XML that defines the layout of the view.
- isDefault
- Type:Boolean: Whether the view should be the default view.
- Remarks
- This method does not work with Owner lookups. Owner lookups are used to assign user-owned records.
DefaultView
You can detect which view is the default view to be shown to allow users to select records in a lookup and change the default view using getDefaultView and setDefaultView.
getDefaultView
Returns the Id value of the default lookup dialog view.
Xrm.Page.getControl(arg).getDefaultView()
- Return Value
- Type: String. The Id value of the default view.
setDefaultView
Sets the default view for the lookup control dialog.
Xrm.Page.getControl(arg).setDefaultView(viewGuid)
- Arguments
- Type: String. The Id of the view to be set as the default view.
PreSearch event
You can add or remove event handlers for the Lookup Control PreSearch Event using the addPreSearch and removePreSearch methods.
Use the PreSearch event to control what results are displayed for the control using the form data current as the user is beginning to search for records.
Both of these methods have the Execution context (client-side reference) passed as the first parameter.
addPreSearch
Use this method to apply changes to lookups based on values current just as the user is about to view results for the lookup.
Xrm.Page.getControl(arg).addPreSearch(handler)
- Arguments
- Type: Function to add.
- Remarks
- This method is only available for Updated Entities.
The argument is a function that will be run just before the search to provide results for a lookup occurs. You can use this handler to call one of the other lookup control functions and improve the results to be displayed in the lookup.
removePreSearch
Use this method to remove event handler functions that have previously been set for the PreSearch event.
Xrm.Page.getControl(arg).removePreSearch(handler)
- Arguments
- Type: Function to remove.
- Remarks
- This method is only available for Updated Entities.
Use setNotification to display a notification about the control and clearNotification to remove it.
setNotification
Display a message near the control to indicate that data is not valid. When this method is used on Microsoft Dynamics CRM for tablets a red “X” icon appears next to the control. Tapping on the icon will display the message.
Xrm.Page.getControl(arg).setNotification(message,uniqueId)
Remarks
Setting a notification on a control will block the form from saving.
This method is only available for Updated Entities.
Arguments
- message
- Type: String: The message to display.
- uniqueId
- Type: String: The id to use to clear just this message when using clearNotification.
Return Value
Type: Boolean : Indicates whether the method succeeded.
clearNotification
Remove a message already displayed for a control.
Xrm.Page.getControl(arg).clearNotification(uniqueId)
Arguments
- uniqueId
- Type: String: The id to use to clear a specific message set using setNotification.
If the uniqueId parameter is not used the current notification shown will be removed.
Remarks
This method is only available for Updated Entities.
Return Value
Type: Boolean: Indicates whether the method succeeded.
Use the addOption, clearOptions, and removeOption methods to manipulate options available for OptionSet controls. See Sample: Create dependent OptionSets (picklists)for an example of these functions being put to use.
addOption
Adds an option to an option set control.
Xrm.Page.getControl(arg).addOption(option, [index])
| Important |
|---|
| This method does not check that the values within the options you add are valid. You should only add options that have been defined for the specific option set attribute that the control is bound to. Use the attribute getOptions or getOption methods to get valid option objects to add using this method. |
- Arguments
-
- option
- Type: Object: An option object to add to the OptionSet.
- index
- Type: Number: (Optional) The index position to place the new option. If not provided the option will be added to the end.
clearOptions
Clears all options from an Option Set control.
Xrm.Page.getControl(arg).clearOptions()
removeOption
Removes an option from an Option Set control.
Xrm.Page.getControl(arg).removeOption(number)
- Arguments
- Type: Number: The value of the option you want to remove.
Refreshes the data displayed in a Sub-Grid
Xrm.Page.getControl(arg).refresh()
| Note |
|---|
| The refresh method is not available in the form OnLoad Event. |
Sets the focus on the control.
Xrm.Page.getControl(arg).setFocus()
Specify whether a date control should show the time portion of the date.
Control Types: standard control for datetime attributes.
Xrm.Page.getControl(arg).setShowTime(bool)
Remarks
This method is only available for Updated Entities.
Determine which controls are visible and show or hide them using the getVisible and setVisible methods.
getVisible
Returns a value that indicates whether the control is currently visible.
| Note |
|---|
| If the containing section or tab for this control is not visible, this method can still return true. To make certain that the control is actually visible; you need to also check the visibility of the containing elements. |
Xrm.Page.getControl(arg).getVisible()
- Return Value
- Type: Boolean. True if the control is visible, otherwise false.
setVisible
Sets a value that indicates whether the control is visible.
Xrm.Page.getControl(arg).setVisible(bool)
- Arguments
- Type: Boolean. True if the control should be visible, otherwise false.
| Note |
|---|
| When you selectively show fields to users in code that runs in the Onload event, we recommend that you configure the fields to not be visible by default and then usesetVisible(true) to show the fields when conditions are right. Using setVisible(false) to hide fields in the Onload event may result in the field briefly appearing to the user before being hidden.
If you are hiding a larger number of fields using setVisible(false), consider if you can group them together into tabs or sections and hide the tab or section rather than the fields separately. This will provide better performance. |
Use these methods to interact with web resource and IFRAME controls.
| Note |
|---|
| These methods does not work with Microsoft Dynamics CRM for tablets. |
Data
Web resources have a special query string parameter named data to pass custom data. The getData and setData methods only work for Silverlight web resource added to a form. For more information see Passing Data from a Form to an Embedded Silverlight Web Resource.
For web page (HTML) web resources, the data parameter can be extracted from the getSrc method or set using the setSrc method.
getData
Returns the value of the data query string parameter passed to a Silverlight web resource.
Xrm.Page.getControl(arg).getData()
- Return Value
- Type: String. The data value passed to the Silverlight web resource.
setData
Sets the value of the data query string parameter passed to a Silverlight web resource.
Xrm.Page.getControl(arg).setData(string)
- Arguments
- Type: String. The data value to pass to the Silverlight web resource.
getInitialUrl
Returns the default URL that an IFRAME control is configured to display. This method is not available for web resources.
Xrm.Page.getControl(arg).getInitialUrl()
- Return Value
- Type: String. The initial URL.
getObject
Returns the object in the form that represents an I-frame or web resource.
Xrm.Page.getControl(arg).getObject()
Src
IFRAMEs or web resources have a src property to define what to display in the embedded window. You can get or change the src property using the getSrc and setSrcmethods.
getSrc
Returns the current URL being displayed in an IFRAME or web resource.
Xrm.Page.getControl(arg).getSrc()
- Return Value
- Type: String. A URL representing the src property of the IFRAME or web resource.
setSrc
Sets the URL to be displayed in an IFRAME or web resource.
Xrm.Page.getControl(arg).setSrc(string)
- Arguments
- Type: String: The URL.
SOURCE : mscrm.com
