Re-usable JScript Libraries in Dynamics CRM 2011

Introduction: Web Resources and JScript Libraries

One of the most remarkable improvements in Dynamics CRM 2011 is the broadened scope for “declarative customizations” – i.e., those not requiring code. If you’re just starting out with the new version and have some customization experience with CRM 4.0, a good place to see this is in working with lookups. Nearly every day I discover a useful application that required code in CRM 4.0 but can be done in CRM 2011 entirely by customizing properties of the new and improved lookup field.

Topics like the one I present here are covered in my subscription series of 4-hour training sessions, Dynamics CRM 2011 Essentials. Find out more and register here…

For example, check out the code required to create a filtered lookup in CRM 4.0 and then compare it to the no-code-form-editor-only approach in CRM 2011 (the latter example is illustrated in the demo at the end of the article).

That being said…there are still plenty of situations requiring some code. Fortunately, when you run into one of these, the improvements in CRM 2011 are just as significant. The ones I want to talk about here – re-usable libraries of JScript code – are part of a brand-new construct known as a “web resource”. Think of web resources as virtual files: resources that can be stored in the CRM 2011 database that in CRM 4.0 would have required a physical disk file. I presented an introductory session at the recent Extreme 2010 show on web resources, and wrote up a summary article here.

In this article I return to the “useful CRM form scripts” theme of the articles you’ll find this in the Trick Bag’s form scripts category: this article is effectively the “hello world” version of working with form scripts in CRM 2011. My experience is that the CRM 2011 approach is different enough from CRM 4.0 that there’s a short, sharp learning curve; hopefully this article will help. The good news is, once you get used to working with JScript web resources, you’ll find that the benefits of having re-usable libraries of form script functions will far outweigh the costs of learning how they work!

If you ever wrote CRM 4.0 form script to turn a phone number entered like this – 6306667667 – into something like this – (630)666-7667

– you probably started by grabbing code from somewhere on the web or something you’d written previously, and placing it on the Change event of the phone number field on a form. The account entity has ten phone number fields (including fax numbers) and the contact entity (including pager numbers) probably has more. So if you implemented this on 20 fields and then had to fix a bug…you had your work cut out for you!

There were techniques in CRM 4.0 to make this a little easier:

You could place a single function in the load event of a form and then call that function from the change event of a form field.
You could actually create a library of re-usable JScript functions, placed by convention in the ISV folder on your CRM server.

Both of these had problems, though: The first one only works for a single entity, so you’d still have to make changes in multiple places. The second involved a fair amount of plumbing to set it up, and created a pretty serious feature gap between CRM Online and on-premise.
In the next section I’ll focus on the mechanics of creating JScript libraries and calling their functions; if you already know the basics and want to see the FormatPhoneNumber bit, skip to the following section.

Example: CRM 2011 Hello World

How do you create your first JScript library and call a function? Here’s a step-by-step hello world example, assuming you’re a user with something like the System Administrator security role:

On the site map, click Settings, and then click Customizations.
On the Customizations page, click Customize the System.
In left navigation, click Web Resources, and then click New.
In the Web Resource dialog, type a Name and a Display Name. (The Name is the schema name, so it can’t have spaces or special characters.)
In the Type drop-down, select Script, and then click Save.

At this point you can browse out to disk and upload a file if you have one. If you’re just starting out, however, you might not have one that will work, because the new object model in CRM 2011 requires some slight differences in the JScript code. In any event, this is the “hello world” example, so I’ll take a shortcut:
Rather than uploading a file, you can simply click the Text Editor button to open up the default editor. What you’re creating in here is the function that will be called from a form event – that is, will be identified as the “event handler” for a form event. To focus specifically on the mechanics, here’s as simple an example as I can come up with:

This shows what it might look like after you clicked the Text Editor button and wrote your function.
Click OK to save the function, then click Save & Close in the Web Resource window.
Web resources need to be published in order to use them, so with your web resource selected in the list, click Publish on the toolbar.

Now that your function’s ready to use, how do you use it? To illustrate the point that functions contained within a Script web resource are re-usable across any entity form in your CRM, I’ll do the next step-by-step generically. Just think: with the exact same code you can provide your users a cheery greeting regardless of which entity’s form they happen to be opening!!! J

Navigate to the grid for any record type, and click the Customize tab on the ribbon.
In the Design group, click Form. The form editor opens.
Click Form Properties in the Form group.
In the Form Libraries section, click Add. The Look Up Record dialog should appear and you should see your JScript library. (This lookup is context sensitive and in this context knows the only kind of web resource that can go here is a JScript library.) In my example, it looks like this:
Select it and click OK. All functions contained in that library are now available as event handlers for any control on the form. (You can have multiple form libraries for a single form, as well as multiple handlers for a single control on the form.)
To call the function, scroll down to the Event Handlers section. Click the Control drop-down, and notice that you can select ANY control on the form right from here: even though this dialog is for form properties, you aren’t restricted to only accessing the OnLoad and OnChange events for the form as in CRM 4.0
But for this example, I’ll stick to the form load: select Form in the Control list, OnLoad in the Event list, and then click the Add button.
You need to type the name of the function (remember JScript is case-sensitive) in the Function field, and then click the Enabled checkbox:
Now click OK, then OK again to close out the Form Properties dialog. Preview the function from within the form editor to see how it works.

Example: FormatPhoneNumber

OK, now that we’ve seen how the mechanics work, let’s do something useful! For the step-by-step example I’ll do next, I’m going to take a slightly different approach that will end up with the same result: I’ll start out from the account form, and create the JScript Library web resource on the fly, illustrating another good example of “in-place” customization. But the library I create will be equally accessible from any entity in CRM, and the FormatPhoneNumber function is written so it can be called from any phone number field.

Navigate to the accounts grid, and click the Customize tab on the ribbon.
In the Design group, click Form.
In the Form group, click Form Properties, and then in the Form Properties dialog, click Add in the Form Libraries section.
In the Look Up Record dialog, click New. (This is the “creating it on the fly” part.) The Web Resource: New window appears. I’ll call mine “CommonFunctions”, with an appropriate Display Name, select Script (JScript) in the Type drop-down, and then click Save:

Click Text Editor, and enter the code you see in the following screenshot:

A couple quick points about this JScript function:

A couple quick points about this JScript function:

Even if I have a disk file I could upload, it’s just as easy to copy it to the clipboard and then paste it into the editor.
Notice the “context” parameter. This is important if the function is intended for re-use; you’ll see that in a minute when we call it as an event handler.

Click OK to save the function, and then click Publish in the Actions group on the Web Resource ribbon. Even though I did this from within Account, it will be published as a web resource available from anywhere. Then click Save and Close to close out of the web resource window, and you should be back in the Look Up Record dialog (remember? From step 4 above.)
Then select the function library and click OK, and you should be back on the Form Properties dialog, with your function library added as an available library:

Now you have a couple options: you can either click OK to return to the form editor and locate the phone number fields you want to use the function on, OR do it the cool new time-saving way I’ll do here:
Keep the Form Properties dialog open and select Main Phone in the control list.
Then click Add in the Event Handlers section to open the Handler Properties dialog.
Type the function name – FormatPhoneNumber – in the Function field, click the Enabled checkbox, and make sure this time to click the Pass execution context as first parameter checkbox:
Now click OK, and then OK again.
Preview the form and test how it works. Since I added the event handler to the change event of the Main Phone field, I’ll do my testing on that one: I’m scolded if I don’t enter a 10-character phone number, and if I do enter one I’m rewarded with a nice standard phone number format. (as long as you’re talking about US phone numbers, anyway!)
Of course, the payoff is that you can now navigate to any entity and use the same function to provide formatting for any phone number field. After you finish off the account form, go to contacts, then leads, and so on.
And by the way: if you get all the way to step 12 and nothing happens, navigate to the web resource through the customization UI (Settings, Customizations, Customize the System, Web Resources) and publish the library of functions. I’ve had intermittent success with the shortcut approach I took here (where I published in step 6 after doing the “in-place” customization approach.) I believe it should work like that but sometimes it seems like it … doesn’t… quite. Anyway, that’s what betas are for.
…and in conclusion…
I meant to record a demo of this so you could get a feel for how much time this can save you. But I ran out of time: my wife told me all she wants for Christmas is a one-second needle and I’m afraid Walgreens will already have run out! I hope you got your shopping done. Merry Christmas and season’s greetings to you & yours – I’ve got to go look for a one-second needle.