Use JavaScript with Microsoft Dynamics 365

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

Microsoft Dynamics 365 (online & on-premises) provide many opportunities to use JavaScript. All JavaScript used in Microsoft Dynamics 365 is added by creating JavaScript web resources. This topic has information for developers who use JavaScript and includes links to relevant topics in the Microsoft Dynamics 365 SDK and other sources.

In This Topic

Areas where you can use JavaScript in Microsoft Dynamics 365

Use of jQuery

Write JavaScript for multiple browsers

JavaScript programming best practices

Debugging JavaScript in Microsoft Dynamics 365

Areas where you can use JavaScript in Microsoft Dynamics 365

You can use JavaScript to perform actions in form scripts, command bar (ribbon) commands, and web resources.

Form scripts

The most common use of JavaScript in Microsoft Dynamics 365 is to add functions as event handlers for entity form events. For more information, see Write code for Microsoft Dynamics 365 forms.

Command bar (ribbon) commands

When you customize the Microsoft Dynamics 365 command bar, you can configure commands for controls that you add. These commands contain rules that control whether the control is enabled and what action is performed when the control is used. For more information, see Customize commands and the ribbon.

Web resources

Microsoft Dynamics 365 provides an organization-owned entity that stores a binary representation of a file that can be accessed by using a URL. This file is called a web resource. There are several types of web resources. A web resource that represents a JavaScript library is called a JavaScript web resource. You can use a webpage (HTML) web resource to provide a user interface with JavaScript libraries included just as you would for files on a web server. Because these files are part of Microsoft Dynamics 365, users who access them are already authenticated. Therefore, you can use Microsoft Dynamics 365 web services without having to write code to authenticate the user. For more information, see Web resources for Microsoft Dynamics 365 and Work with Dynamics 365 data using web resources.

Use of jQuery

• Use jQuery with HTML web resources
  We recommend that you use jQuery together with HTML web resources to provide user interfaces because it is an excellent cross-browser library.

  With HTML web resources, you control the libraries that are present and there is no restriction against manipulating the DOM. Feel free to use jQuery within your HTML Web resources.

• Avoid using jQuery with form scripts or ribbon commands
  We do not recommend using jQuery in form scripts and ribbon commands.

  Most of the benefit provided by jQuery is that it allows for easy cross-browser manipulation of the DOM. This is explicitly unsupported within form scripts and ribbon commands. Restrict your scripts to use the Xrm.Page and Xrm.Utility libraries available in form scripts and ribbon commands. If you decide to use the remaining capabilities of jQuery that are useful with Microsoft Dynamics 365 and include the ability to use $.ajax, consider the following:

  • For best performance, don’t load jQuery in the page if you do not need it

  • Using $.ajax to perform requests against the Microsoft Dynamics 365 web services is supported, but there are alternatives. The alternative to using $.ajax is to use the browsers XMLHttpRequest object directly. The jQuery $.ajax method is just a wrapper for this object. If you use the native XMLHttpRequest object directly, you do not need to load jQuery.

  • Each version of jQuery that is loaded in a page can be a different version. Different versions of jQuery have different behaviors and these can cause problems when multiple versions of jQuery are loaded on the same page. There is a technique to mitigate this, but it depends on editing the jQuery library and any other libraries that depend on jQuery. More information: jQuery and jQuery UI with Dynamics CRM 2011 & 2013, jQuery.noConflict()

    Note

    Following Microsoft Dynamics CRM Online 2015 Update 1, form scripts run in a different scope than the jQuery instance used by the application. This means that there may not be an instance of jQuery available when your code attempts to use jQuery.noConflict. If you must use jQuery, you should first detect whether an instance of jQuery exists before you attempt to use jQuery.noConflict.

Write JavaScript for multiple browsers

Because you don’t know what browser will be in use, you should make sure that any scripts that you use will work with all supported browsers. Most of the significant differences between Internet Explorer and other browser have to do with HTML and XML DOM manipulation. Because HTML DOM manipulation is not supported, if script logic is only performing supported actions and using the Xrm.Page API the changes required to support other browsers could be small. Use the Custom Code Validation Tool to identify code that only works for Internet Explorer.

A cross-browser library like jQuery is a good solution for developing web resources but should not be necessary for form scripts or ribbon commands. More information: Use of jQuery

Support for other browsers

Because Microsoft Dynamics 365 (online & on-premises) supports W3C standards, the application will be accessible using any modern browser and from any platform that supports those standards. However Microsoft Dynamics 365 will only be tested using a specific set of browsers and platforms. For the list of supported platforms and browsers see TechNet: Supported web browsers.

If you use a browser, or browser version, that is not supported and you type just the server name or server name with organization as the URL, you will be redirected to the Microsoft Dynamics 365 for phones page. The Dynamics 365 for phones pages can be expected to work properly on most browsers, such as browsers used in mobile devices, with limited functionality.

JavaScript programming best practices

The following sections describe best practices when you use JavaScript with Microsoft Dynamics 365.

Avoid using unsupported methods

On the Internet, you can find many examples or suggestions that describe using unsupported methods. These may include leveraging undocumented internal function for page controls. These methods may work but because they are not supported you can’t expect that they will continue to work in future versions of Microsoft Dynamics 365.

Use the Custom Code Validation Tool to identify code that is using unsupported methods.

Use a cross-browser JavaScript library for HTML web resource user interfaces

A cross-browser JavaScript library, such as jQuery, provides many advantages when developing HTML web resources that must support multiple browsers. JavaScript libraries like jQuery provide a unified development experience for all browsers supported by Microsoft Dynamics 365. These capabilities are appropriate when you are using HTML web resources to provide user interfaces. JavaScript libraries like jQuery provide consistent ways to interact with the Document Object Model (DOM).

Do not use jQuery for form script or commands

We do not recommend or support using jQuery for any pages within the application. This includes form scripts and ribbon commands. More information: Use of jQuery.

Recognize limitations for content delivery network (CDN) libraries

Content delivery network (CDN) JavaScript libraries provide many advantages for public websites. Because these libraries are hosted on the Internet, you do not need to create web resources that contain the content of the libraries. For Microsoft Dynamics 365 you should consider the following issues before you use a CDN JavaScript library.

• Users of the Microsoft Dynamics 365 for Microsoft Office Outlook with Offline Access client have the capability to work with no Internet connection while working offline. If you are depending on an Internet connection for your JavaScript libraries, your code will fail.

• Some organizations will restrict Internet access for employees. Unless they configure the network to allow access to the CDN library sites, your code may fail for those organizations.

The alternative to using CDN libraries is to create a script (JavaScript) web resource with the contents of the library. Because web resources are organization-owned entities they will be synchronized when a Microsoft Dynamics 365 for Outlook with Offline Access user goes offline. Because these web resources now become part of the application they will not be blocked if an organization restricts access to the Internet.

Use feature detection when writing functions for multiple browsers

Even when you use a cross-browser library like jQuery, you need to be very aware of differences between browsers. You can generally detect which browser is being used by querying the navigator.useragent property. This is called browser detection. Browser detection is not a good strategy for most cases because it can’t take into account what features newer versions of a browser have. Also, some browsers provide the capability to modify the navigation.useragent property so that they appear to be a different browser.

Feature detection is the recommended approach. By detecting what features are available, you can create code paths for the browsers you support without knowing exactly which browser is being used. For more information about feature detection, see How to Detect Features Instead of Browsers.

Do not access the DOM

JavaScript developers are used to interacting with Document Object Model (DOM) elements in code. You might use the window.getElementById method or the jQuery library. You are free to use these techniques in your HTML web resources, but they are not supported to access elements in Microsoft Dynamics 365 application pages or entity forms. Instead, access to entity form elements are exposed through the Xrm.Page object model. The Microsoft Dynamics 365 development team reserves the right to change how pages are composed, including the ID values for elements, so using the Xrm.Page object model protects your code from changes in how pages are implemented. For more information, see Use the Xrm.Page object model.

Define unique names for your JavaScript functions

When you are the only developer for an HTML page you can easily manage the names of the JavaScript functions you use. In Microsoft Dynamics 365, other solutions may add JavaScript functions to the page where your function is used.

If two JavaScript functions on a page have the same name, the first function defined is overwritten by the second. For this reason, make sure that you define unique names for your JavaScript functions. For more information, see Creating script libraries.

Use asynchronous data access methods

When you access data by using the Microsoft Dynamics 365 web services, always use an XMLHttpRequest that is configured to execute asynchronously. The reason is that the browser operates on a single thread. If that thread is being used to execute a long-running process synchronously the browser will stop responding.

Debugging JavaScript in Microsoft Dynamics 365

Each browser provides some kind of debugging extension. Internet Explorer provides developer tools you can use to debug scripts in Microsoft Dynamics 365. The Internet Explorer developer tools can be opened by pressing F12 when viewing a page using Internet Explorer. For more information, see Using the F12 developer tools.

For Google Chrome, press F12 to open developer tools. Firebug is a popular browser extension for web development using Mozilla Firefox. For Apple Safari, you must first select the Show Develop menu in menu bar in Advanced Preferences. Then you can select Show Web Inspector from the Develop menu.

You can also use Microsoft Visual Studio. For more information, see How to Debug JScript in Microsoft Dynamics CRM 2011.

When you use JavaScript libraries in Microsoft Dynamics 365, your libraries are loaded with the web page. It can sometimes be difficult to isolate your specific library in the debugging environment. When using debugging tools in Microsoft Edge, on the Debugger tab, click on the folder icon at the top-left corner, and expand the available scripts and find the one with the name that corresponds to the name of your JavaScript web resource, such as the new_myCustomJavaScript.js web resource shown below. You can also search for your JavaScript library by typing the file name in the search box.

Debugging tools for different browsers have similar capabilities. Once you have found your library, you can set a break point and recreate the event that should cause your code to run.

In the new interactive service hub client (introduced in Dynamics 365), Dynamics 365 dynamically injects the contents of your JavaScript library instead of loading it with the page. This implies that you cannot set break points in your code because every time the page loads, your code is injected into one of the dynamics libraries that will prevent the break point to be hit. In this case, you will have to use some other techniques to debug your code. More information: Blog: Debugging JavaScript code in CRM using browser developer tools

Write messages to the console

Using the window.alert method when debugging JavaScript is still a common way to troubleshoot code in the application. But now that all modern browsers provide easy access to debugging tools, it is not a best practice, especially when others might be using the application you are debugging.

Consider writing your messages to the console instead. The following is a small function you can add to your libraries that you can use to send any messages you want to view to the console when it is open.

function writeToConsole(message)
{
 if (typeof console != 'undefined') {
  console.log(message);
 }
}

Unlike using the alert method, if you forget to remove any code that uses this function, people using the application will not see your messages.

See Also

Extend Microsoft Dynamics 365 on the client
Work with Dynamics 365 data using web resources
Extend Microsoft Dynamics 365 on the server
Write code for Microsoft Dynamics 365 forms
Customize commands and the ribbon
Web resources for Microsoft Dynamics 365
Get started with the Microsoft Dynamics 365 Web API (client-side JavaScript)
Use the Xrm.Page object model
Blog: Debugging JavaScript code in CRM using browser developer tools

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright