Microsoft Dynamics CRM allows the addition of JavaScript to forms which enables the extension of the basic solution in many ways. CRM Developers and customizers make extensive use of this when tailoring CRM systems to meet customer requirements. The web is littered with many people publishing useful code snippets which with very little JavaScript knowledge you can inject into CRM forms.

But I haven’t found many people describing the basics of JavaScript to enable some new to CRM to understand the concepts of how to add code to their CRM system and custom entities.

I know MANY of the CRM “experts” out there will know this stuff already. This post isn’t for you guys.

Here I intend to simply explain the absolute basics, just enough to get someone started. Hopefully then you can start to dive into the many thousands of posts out there describing all sorts of clever tricks.

Here goes ……

I guess the first question, has to be, what is JavaScript? Below is what Wikipedia says on the subject.

Got it??? Or to explain this in more straight forward terms, JavaScript is a “simple” scripting language that is supported by all web browsers. Your CRM forms are displayed in a web browser so JavaScript is used to control how those forms behave. Got it now?

I guess the second question might be “Why would I use JavaScript?” ….. Microsoft Dynamics CRM is a highly configurable solution but changes simply aren’t possible using the “out of the box” configuration options alone. For example, you can use business rules to hide and show fields but they can’t hide sections or tabs. But JavaScript can. When new to CRM you’ll possibly find that pretty much everything you need to do can be achieved with simple customizations but at some point you’ll start to have requirements which can’t be achieved with customizations alone. At that point, one of the options you can turn to is JavaScript. (FYI: Other options include workflows and .net plugins. But this post is about JavaScript!)

Creating a JavaScript library for an entity.

Before starting any coding, first off we will need to create a JavaScript web resource and link it to the form you wish to customize. Doing that is a lot simpler than it sounds. For this you are going to need to have the CRM System Administrator or System Customizer role. If you haven’t you’ll need to speak to your systems administrator before continuing.

Log into your CRM system and navigate settings and then select Customizations. You’ll end up on the screen below. Select “Customize the System”.

Next you’ll need to find the form you want to change, so on the screen that pops up open the entities collection. Then find the entity you want to change. I’m going to make a change to account. Which is convenient as it’s the first entity in the list! Now select the Forms option. As I’ve done below.

Some entities (like Account) may already have multiple forms. You can also create additional ones. (Maybe that will be the subject of another post in the future!) For now, I want to make a change to the “main” / default form on account. So I’m going to select the form called “Account” that has a Form Type of “Main”.

Having selected the form you’ll be presented with a screen something like the one below. From here you can move fields around on the form, add new field etc. In this example though we are going to select the “Form Properties” ribbon button to add some JavaScript.

Having selected the “Form Properties” button, a screen like the one below will pop-up. This shows you the Form Libraries and Event Handlers for this form.

The Form Libraries is essentially a list of one or more files containing your JavaScript code. The Event Handlers (which I’ll cover in a minute) are then used to say which functions from those libraries will by triggered on what events.

More on Event Handlers soon, for now simply click the Add button under Form Libraries.

Having clicked Add you will be presented with the dialogue shown below. This allows you to add existing JavaScript libraries to your form. Or (as in our case) you can create new ones. So this time, just click New.

When you click “New” another dialogue will pop-up. You can then complete several fields.

Name: This is mandatory, just give it a sensible name. I tend to reference the entity the JavaScript relates to and / or the form.

Display Name: This is optional but it might help you later to have a slightly more verbose name to find your code.

Description: Again this is optional. To be honest I often leave this blank. But you could fill in some details if you like.

Type: This field is mandatory. You need to set it to “Script (JScript)”

At this point if you click save it will complain that the webresource is empty. So click “Text Editor”, we’ll just add something to allow us to create the library for now.

Once you click Text Editor the screen below will show. At this point you can start to enter your code. But let’s keep it simple for now. You can see below I have just created two functions. Neither of which does anything yet.

function onLoad() {

}

function onChange () {

}

Assuming you are new to JavaScript, the keyword function is used to define your function. Then then code which makes up the function will be between “{” and “}” brackets.

One point to be aware of is that JavaScript is case sensitive. Meaning onLoad and onLOAD would be two different functions!

Once you’ve entered this simple code click “ok”.

You will now see the previous dialog again, this time click save. Then press “x” to close the window.

You will now be returned to the previous look-up dialogue. But you’ll notice the details for the JavaScript library you’ve just created will be populated. Just click “Add” now.

Finally you will be returned to the form properties dialogue. This might all feel like a lot of pop-ups. Because it is! But it’s quite simple really.

Now you’ve created your form library, lets add an event handler. (or two.)

Adding Event Handlers to an entity.

Events are a pretty simple concept, whenever a form loads, is saved or a field changes an event is triggered. The event handlers let you link a JavaScript function to each event.

In this example, I want to show you how to link a function to the onLoad and onChange events on a form. Conveniently the form onLoad event is the one displayed by default, so let’s start with that. Just click Add.

Having clicked Add you’ll be presented with a dialog similar to the one below. The first step is to pick the library to use. In this simple example we have only one file containing all of our code. So that will already be selected. Meaning you just have to type the name of the function for the onLoad event. We called ours “onLoad” so just enter that. Not forgetting this is case sensitive! And also ONLY enter the function name. (onLoad() or onLoad(); are invalid here!) Unfortunately the system does no syntax checking here, so be careful to type the function name correctly.

Now let’s also add an onChange event to the form. You can do this directly from this dialog. But it is worth knowing that you can also access this same dialog directly from the form designer. When you double click on a field name in the form design you can select the “Events” tab which gives access to this same screen. (As I’ve shown below.)

To set an onchange event, first of all change the “Control” drop down from form to show the field you want to link the onChange function to. In this example, select “Account Name”. Then the Event dropdown must be set to “onChange”. Next click “Add” and the same as you did for the onLoad event enter the name of the function you want to trigger. In this simple example “onChange”.

Note: In a more typical example you will probably have several onChange events. So typically you might name them “onChange_AccountName”, “onChange_address1” etc. As you’d want a separate onChange function for each field.

So that is your code library and event handlers defined. Great. Except! At the moment nothing will happen as we didn’t add any code to the functions. So let’s do that now.

A very simple code example

I’m not trying to teach you how to code here! Just the mechanics of inserting the JavaScript code into your form. So we’ll keep this pretty simple.

All I want to do is display a message on the screen when the form loads and also when the account name is changed.

Don’t worry about how the code works at this point! Microsoft Dynamics contains an object called “Xrm.Page”, you can use this to access and interact with all the controls on your form.We are going to make use of this in two ways in this example.

The first line of code (below) is used to display a notification on the form. A notification being a yellow bar to flag something to the user.

Xrm.Page.ui.setFormNotification(“Give some Info!”, “INFO”, “1”);

The second line of code (below) is used to get the content of the account name field.

Xrm.Page.getAttribute(“name”).getValue();

In the onLoad function I want to say, if the account name is blank give a message saying “Don’t forget to put in an account name”. Then when the user changes the account name, I want to say “thanks”.

Onload I’d need this code …

function onLoad() {
  if(Xrm.Page.getAttribute("name").getValue() == null) {
    Xrm.Page.ui.setFormNotification("Don't forget to put in an account name!", "INFO", "1");
  }
}

And onChange I’d need ….

function onChange() {
  if(Xrm.Page.getAttribute("name").getValue != null) {
    Xrm.Page.ui.setFormNotification("THANKS!", "INFO", "1");
  }
}

To add your code, return to the form properties window and click the edit button above the form libraries grid.

Now change the code we entered earlier to look like this and then click ok on the “edit content” dialog and ok again on the form properties dialog. Using the code below.

function onLoad() {
if(Xrm.Page.getAttribute("name").getValue() == null) {
  Xrm.Page.ui.setFormNotification("Don't forget to put in an account name!", "INFO", "1");
  }
}

function onChange() {
  if(Xrm.Page.getAttribute("name").getValue() != null) {
    Xrm.Page.ui.setFormNotification("THANKS!", "INFO", "1");
  }
}

Publish and test your change

Now from the form designed click “save”, to save your change. Then click “Publish”. You should see a yellow box display like the one shown below.

After a short pause you’ll be ready to test your change.

Now go to account in CRM and click NEW to create a new account. Your account form will now look like this. Complete with a “helpful” message in a yellow bar.

Now enter an account name and press tab to move away from the field. Immediately you’ll see the message change as shown below.

If you are new to CRM / JavaScript hopefully you will have found this post useful, you should now be ready to start thinking about more complex changes.

Happy coding! J