JavaScript libraries for Microsoft Dynamics 365

Article
11/28/2016

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

JavaScript libraries are Script (JScript) web resources that contain functions you can use to:

Handle form and field events.
Perform actions for controls configured in the Ribbon.
Support other functions.

Using JScript libraries

You can use JavaScript libraries much as you would use JavaScript libraries in any web application.

Associate functions with Form and Field events

You can associate up to 50 script web resources so that they will be loaded with an entity form.

After you add a library to the form, it’s available to all events in the form. For any event, you can decide which functions to be the event handlers. You can specify up to 50 functions as event handlers for any event.

Associate functions at run time

You can add functions to the OnChange attribute, form OnSave, and lookup control PreSearch events at run time by using Xrm.Page.data.entity attribute.addOnChange, the Xrm.Page.data.entity.addOnSave, and the lookup control addPreSearch methods. When these methods are used, the function is added at the bottom of the event handler pipeline and they receive the execution context as the first parameter. You can use the corresponding removeOnChange,removeOnSave and removePreSearch methods to remove functions added this way.

Execution context

Each event handler can be configured to accept an execution context object as the first parameter. The execution context includes functions that can be called to determine:

Depth: The relative order in which this handler is executed.
Event Source: A reference to the object that initiated the event.

This capability is important when you’re creating a function that may respond to events from several different form or field events.
Shared Variables: This allows a function to set a variable as a key/value pair that can be accessed by other event handlers.

More information: Execution context (client-side reference)

In the handler properties dialog box, you can enter a comma-separated list of string values that will be passed to the function. This can be useful to allow the behavior of a function to be changed without requiring changes to the code.

Associate functions with command bar (Ribbon) commands

Each control in the command bar or Ribbon is associated with a <CommandUIDefinition> (RibbonDiffXml) that contains an <Actions> (RibbonDiffXml) element that contains one or more actions. <JavaScriptFunction> (RibbonDiffXml) is one of the available actions. The JavaScriptFunction element requires a reference to a library and a function in that library.

Develop and test scripts

You can edit scripts through the web resource form or from the Events tab where you configure form libraries and event handlers.

Or, you can use your favorite script editing tool and upload your changes to update your script web resource. You must publish the web resource after you make changes.

Creating script libraries

When you design functions that will be used in JavaScript libraries, your functions may be loaded into a form with other JavaScript libraries. If another library contains a function that has the same name as a function you provide, whichever function is loaded last is defined for the page. To avoid having your functions overwritten by functions in another library, you should make sure that your functions have unique names.

Two strategies that you can use to help make sure your functions have unique names are:

Unique function prefix
Define each of your functions using the standard syntax with a consistent name that includes a unique naming convention, as shown in the following example.
```
function MyUniqueName_performMyAction()
{
// Code to perform your action.
}
```
Namespaced library names
Associate each of your functions with a JavaScript object to create a kind of namespace to use when you call your functions, as shown in the following example.
```
//If the MyUniqueName namespace object isn’t defined, create it.
if (typeof (MyUniqueName) == "undefined")
 { MyUniqueName = {}; }
  // Create Namespace container for functions in this library;
  MyUniqueName.MyFunctions = {
   performMyAction: function(){
   // Code to perform your action.
   //Call another function in your library
   this.anotherAction();
  },
  anotherAction: function(){
   // Code in another function
  }
};
```
Then when you use your function you can specify the full name. The following example shows this.
```
MyUniqueName.MyFunctions.performMyAction();
```
If you call a function within another function you can use the this keyword as a shortcut to the object that contains both functions. However, if your function is being used as an event handler, the this keyword will refer to the object that the event is occurring on.

Debugging Scripts

Each browser has their own set of developer tools. The following instructions describe using Internet Explorer.

Debug script in Microsoft Dynamics 365 forms

Press F12 to open the developer tools.
On the Script tab, to the right of the Start Debugging button, use the drop-down list to locate your JavaScript library.
Set a breakpoint by clicking the left margin in your function.
Click Start Debugging.
If your script is in the Onload event, you may have to select the Microsoft Dynamics 365 window and press F5 to reload the window.

For more information, see Debugging Script with Developer Tools.