Xrm.Utility (client-side reference)
Applies To: Dynamics CRM 2013
The Xrm.Utility object provides a container for useful functions not directly related to the current page.
These functions are available in every application page that supports scripting. You can use them in form scripts or in ribbon commands. For HTML web resources, they are available when you include the ClientGlobalContext.js.aspx page. For more information, see GetGlobalContext function and ClientGlobalContext.js.aspx (client-side reference).
- Dialogs
Use alertDialog and confirmDialog display messages to users and set code to execute based on their response. These functions must be used with Microsoft Dynamics CRM for tablets in place of the window.alert and window.confirm methods.
- isActivityType
Determine if an entity is an activity entity.
- openEntityForm
Opens an entity form.
- openWebResource
Opens an HTML web resource.
There are two types of dialogs: alertDialog and confirmDialog. These are included for use with scripts that will work with Microsoft Dynamics CRM for tablets. CRM for tablets will not allow the use of JavaScript functions that block the flow of code such as window.alert and window.confirm. Use these methods in place of those methods in case you need to display a message to the user. They key difference is that these methods will not block code until a user closes them. They contain a callback function parameter to indicate what code should be executed depending on the user’s response.
Note |
|---|
In Microsoft Dynamics CRM for tablets any use of the window.alert method will be overridden to use Xrm.Utility.alertDialog without a callback. This will display the message but will not block the execution of code as window.alert does. This mapping of window.alert to Xrm.Utility.alertDialog in CRM for tablets is deprecated and will be removed in the next major release. You should migrate any code you have today to use Xrm.Utility.alertDialog rather than window.alert. |
Displays a dialog box containing an application-defined message.
Xrm.Utility.alertDialog(message,onCloseCallback)
Parameters
- message
Type: String. The text of the message to display in the dialog.
- onCloseCallback
Type: Function. A function to execute when the OK button is clicked.
- Remarks
This method is only available for Updated entities.
Displays a confirmation dialog box that contains an optional message as well as OK and Cancel buttons.
Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)
Parameters
- message
Type: String. The text of the message to display in the dialog.
- yesCloseCallback
Type: Function. A function to execute when the OK button is clicked.
- noCloseCallback
Type: Function. A function to execute when the Cancel button is clicked.
- Remarks
This method is only available for Updated entities.
Determine if an entity is an activity entity.
Xrm.Utility.isActivityType(entityName)
Parameter
- entityName
Type: String. The logicalName of an entity.
Return Value
Type: Boolean. True if the entity is an activity entity, otherwise false.
Opens an entity form.
Xrm.Utility.openEntityForm(name,id,parameters)
Parameters
- name
Type: String
Required: The logical name of an entity.
- id
Type: String
Optional: The string representation of a unique identifier or the record to open in the form. If not set, a form to create a new record is opened.
- parameters
Type: Object
Optional: A dictionary object that passes extra query string parameters to the form. Invalid query string parameters will cause an error.
Valid extra query string parameters are:
Form id: To set the id value of the main form to use when more than one form is available. The parameter is formid.
Default field ids: To set default values for a new record form. For more information, see Set field values using parameters passed to a form.
The navbar and cmdbar parameters described in Query String Parameters for the Main.aspx Page.
Custom query string parameters: A form can be configured to accept custom query string parameters. For more information, see Configure a form to accept custom querystring parameters.
Remarks: Using this function helps ensure that users are not prompted to log in again under certain circumstances.
Examples
- Open a new account record
-
Xrm.Utility.openEntityForm("account"); - Open an existing account record
-
Xrm.Utility.openEntityForm("account","A85C0252-DF8B-E111-997C-00155D8A8410");
- Open a new account record with a specific form and setting default values
-
var parameters = {}; parameters["formid"] = "b053a39a-041a-4356-acef-ddf00182762b"; parameters["name"] = "Test"; parameters["telephone1"] = "(425) 555-1234"; Xrm.Utility.openEntityForm("account", null, parameters);
Opens an HTML web resource.
Note |
|---|
This function will not work with Microsoft Dynamics CRM for tablets. |
Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)
Parameters
- webResourceName
Type: String
Required: The name of the HTML web resource to open.
- webResourceData
Type: String
Optional: Data to be passed into the data parameter.
- width
Type: Number
Optional: The width of the window to open in pixels.
- height
Type: Number
Optional: The height of the window to open in pixels.
Return Value: Window object.
Remarks: An HTML web resource can accept the parameter values described in Pass parameters to HTML web resources. This function only provides for passing in the optional data parameter. To pass values for the other valid parameters, you must append them to the webResourceName parameter.
Examples
- Open an HTML web resource named “new_webResource.htm”
-
Xrm.Utility.openWebResource("new_webResource.htm"); - Open an HTML web resource including a single item of data for the data parameter
-
Xrm.Utility.openWebResource("new_webResource.htm","dataItemValue");
- Open an HTML web resource passing multiple values through the data parameter
-
var customParameters = encodeURIComponent("first=First Value&second=Second Value&third=Third Value"); Xrm.Utility.openWebResource("new_webResource.htm",customParameters);
Note These values have to be extracted from the value of the data parameter in the HTML web resource. For more information, see Sample: Pass multiple values to a web resource through the data parameter
- Open an HTML web resource with the parameters expected by HTML web resources
-
Xrm.Utility.openWebResource("new_webResource.htm?typename=account&userlcid=1033");For more information, see Pass parameters to HTML web resources.
- Open an HTML web resource, setting the height and width
-
Xrm.Utility.openWebResource("new_webResource.htm", null, 300,300);