Export (0) Print
Expand All

JScript Libraries for Microsoft Dynamics CRM

[Applies to: Microsoft Dynamics CRM 2011]

Microsoft JScript 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 JScript libraries much as you would use JScript 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 is available to all events in the form. For any event, you can decide which functions to be the event handler. 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 and the form OnSave events at run-time by using the Xrm.Page.data.entity attribute.addOnChange method and the Xrm.Page.data.entity.addOnSave method. When these methods are used, the function is added at the bottom of the event handler pipeline. You can use the corresponding removeOnChange and removeOnSave 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 are 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.

For more information, see Form Event Handler Execution Context Reference.

Within 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 Ribbon Commands

Each control in the 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 within 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.

For JScript libraries that interact with the Xrm.Page object model in Microsoft Dynamics CRM forms you can use the Xrm.Page Script Library Template to use IntelliSense and perform initial testing of your JScript libraries. For more information, see Use the Xrm.Page Script Library Template.

Creating Script Libraries

When you design functions that will be used within JScript libraries, your functions may be loaded into a form with other JScript 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 that 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 JScript 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 is not 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 this will refer to the object that the event is occurring on.

For some examples, see Xrm.Page Sample Libraries.

Debugging Scripts

With Internet Explorer 8 and JScript libraries, debugging scripts has become much easier.

To debug script in Microsoft Dynamics CRM

  1. While working with Microsoft Dynamics CRM try to reproduce the conditions where an error is occurring by pressing F12 to open the Internet Explorer developer tools.

  2. On the Script tab, to the right of the Start Debugging button, use the drop-down list to locate your JScript library.

  3. Set a breakpoint by clicking the left margin in your function.

  4. Click Start Debugging.

  5. If your script is in the Onload event, you may have to select the Microsoft Dynamics CRM window and press F5 to reload the window.

For more information, see Debugging Script with Developer Tools.

See Also

Microsoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.

Community Additions

ADD
Show:
© 2014 Microsoft