Write and debug scripts for Dynamics 365 for phones and tablets

  • Article

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Microsoft Dynamics 365 for phones and Microsoft Dynamics 365 for tablets use the same form definitions that are used in the web application. Any JavaScript code you add to form event handlers or ribbon commands in the web application may also run within Dynamics 365 mobile clients (phones and tablets). There are some differences you need to be aware of.

In this topic

Some Xrm.Page or window object functions won’t work in Dynamics 365 for phones and tablets

Specify what code will run in Dynamics 365 for phones and tablets

Specify what commands will display in Dynamics 365 for phones and tablets

Be aware of differences between Dynamics 365 mobile clients and the web application in a browser

Debugging scripts for Dynamics 365 for phones and tablets

Some Xrm.Page or window object functions won’t work in Dynamics 365 for phones and tablets

Dynamics 365 mobile clients don’t allow any functions that can block execution of scripts. Common JavaScript functions such as window.alert, window.confirm, and window.prompt won’t work as you expect or will produce errors.

Use the Xrm.UtilityalertDialog and confirmDialog functions to display messages to users. These functions operate differently than window functions because they don’t stop the processing of scripts until the user closes them. They provide callback functions to allow for an asynchronous response to user input. Using window.confirm, window.prompt, or any other native window function that blocks execution of scripts will throw an error.

Note

If you use window.alert in your form scripts, the message you set will automatically be displayed using Xrm.Utility.alertDialog without a callback function specified, but this is temporary and is already considered deprecated. You should move any code using window.alert to use Xrm.Utility.alertDialog instead.

Dynamics 365 mobile clients also do not support the window.open method. If you are looking to open an entity form for a new or existing record, use Xrm.Utility.openEntityForm instead.

The following methods won’t work in Dynamics 365 mobile clients (phones and tablets).

Xrm.Page.context.getCurrentTheme

Xrm.Page.uiViewPort Methods

Xrm.Page.data.entity.getDataXml

Xrm.Page.ui.navigation.items collection

Xrm.Page.ui.formSelector object methods

Xrm.Page.ui tab.setDisplayState

Most of these functions will execute an empty function and return nothing. If you have code that expects a return value from one of these functions it will be undefined.

Additionally, Dynamics 365 for phones does not support web resources and IFRAMES so the client APIs for these controls won't work. Client APIs for web resources and IFRAMES are supported on Dynamics 365 for tablets though. More information: Web resource and IFRAME control methods

Specify what code will run in Dynamics 365 for phones and tablets

When the capabilities of the client API are different you should include code similar to the following to separate the logic you apply for each client.

var isCrmForMobile = (Xrm.Page.context.client.getClient() == "Mobile")
if (isCrmForMobile)
{
 // Code for CRM for phones and tablets only goes here.
}
else
{
 // Code for web browser or CRM for Outlook only goes here.
}
// Code for any client goes here.

Specify what commands will display in Dynamics 365 for phones and tablets

When you use the <JavaScriptFunction> (RibbonDiffXml) action in your custom command bar (ribbon) commands you can also separate your code using Xrm.Page.context.client.getClient. If the action you want to perform won’t work using Dynamics 365 mobile clients, you should include display rules so that the commands won’t appear in Dynamics 365 for tablets. By default, any command defined will display in Dynamics 365 mobile clients unless you explicitly configure it not to. As a rule, you should define the following display rule and include it in every command unless you know it will work using Dynamics 365 mobile clients.

<DisplayRule Id="My.HideOnModern">
 <CommandClientTypeRule Type="Modern"
                        InvertResult="true" />
</DisplayRule>

Be aware of differences between Dynamics 365 mobile clients and the web application in a browser

Other than the functions described in Some Xrm.Page or window object functions won’t work in Dynamics 365 for phones and tablets, you should also be aware that there are other differences.

  • Composite Fields
    Dynamics 365 mobile clients implement composite fields differently. Dynamics 365 mobile clients won’t include composite attributes. They automatically substitute the constituent attributes and display them instead. More information: Write scripts for composite attributes.

Debugging scripts for Dynamics 365 for phones and tablets

Because Dynamics 365 for phones or Dynamics 365 for tabletsare apps, the normal JavaScript debugging tools you can use in the browser aren’t available. We recommend the following procedure to test and debug your form scripts and ribbon commands:

  1. Test your scripts thoroughly using the web application.

  2. As part of testing using the web browser, reverse the criteria when you check for the client using Xrm.Page.context.client.getClient and verify that the logic is appropriate for the experience people should have when using Dynamics 365 mobile clients. The APIs available for Dynamics 365 mobile clientsare a subset of the APIs available for the web browser, so you should be able to test your alternate flow in the web browser.

  3. If possible, install Dynamics 365 mobile clients on a computer with Windows 10 and Microsoft Visual Studio installed. Include debugger statements where you want to launch the debugger using Visual Studio.

  4. Finally, use Xrm.Utility.alertDialog to display values from your code within Dynamics 365 mobile clients.

See Also

Write code for Microsoft Dynamics 365 forms
Use form and field events
Use the Xrm.Page object model
Write scripts for composite attributes
Form scripting quick reference
Client-side programming reference
Command bar or ribbon presentation

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright