Today we will talk about JavaScript Web Resources in Dynamics CRM , but if you are new to CRM then you must be wondering :
What are Web Resources in CRM ?
Web Resources in CRM are the virtual web files that are stored in CRM database and used to implement web page functionalities in CRM. These files can be of HTML, JavaScript, Silverlight, or any other supported types. CRM being a product, comes with an extensive set of features and functionalities. However, most of the times, you would have to extend these existing functionalities to meet your custom requirements. Extending these functionalities generally happens in two ways :
- Extending on Client Side − Using Web Resources and Form Scripting.
- Extending on Server Side − Plugins, Workflows and Web Services (we are going to learn this part in the upcoming chapters).
As mentioned above, extending CRM on the client side is where Web Resources comes in picture. To understand this clearly, consider the following use cases :
- You have a CRM form containing certain fields. CRM provides out-of-the-box features for basic validations such as mandatory fields, field lengths, etc. However what if you would like to have a more complex validation such as validating if the entered phone number is in the correct format, or validating if the entered address actually exists, or if the entered SSN is correct?
- CRM provides out-of-the-box UI customizations such as creating sections and tabs on a form, rearranging fields, etc. However, what if the client wants to build a custom page which shows all the information of the customer coming from their other ERP system?
- CRM comes with a standard ribbon bar, which contains all the buttons and options. What if you want to add a ribbon button of your own?
- Consider that you have an ERP system already in place. What if you would like to open some CRM screens from this ERP system?
- You can always call any external web services in your server-side plugin code. However, what if you would like to call any external web services while you are still on the client-side?
The answer to all these “What ifs” is Web Resources. Every Web Resource can be accessed via its unique URL. You can either upload a Web Resource file or for codebased resources (such as HTML, Jscript, etc.) you can even edit them directly inside CRM. Since Web Resources are stored within CRM, they can easily be migrated from one environment to another together, along with any CRM customizations.
Now that we now what Web Resources are , let’s jump to our next question :
What are JavaScript Web Resources and their applications in Dynamics CRM ?
JScript Web Resources are probably the most important type of web resources that you will be using with Microsoft Dynamics CRM.
Javascript is used in a lot of CRM applications such as :
- Form Event Programming :
Form Event Programming is used to handle client-side behaviors such as what happens when a user opens a form, changes some data, moves through tabs, etc. To achieve such client-side interactions you will be writing JavaScript code and adding it as a JScript Web Resource in CRM. However, the JavaScript code which you will write has to use Dynamic CRM’s Xrm.Page model and not the standard JavaScript DOM. Using Xrm.Page model is Microsoft’s way of coding which ensures that any code you write using this model will be compatible with any future versions of CRM.
- Open Forms , Views and Dialogs with unique URL
- Using OData and SOAP endpoints to interact with web services
- Referencing JavaScript code inside other Web Resources (such as HTML for example)
- Ribbon Customizations
Above we mentioned Xrm.Page model a few times , what is this model and what is it’s functionality ?
Following is the Xrm.Page object’s hierarchy showing the available namespaces, objects, and their collections. You will be using these properties while writing JScript code.
Namespaces in this model include :
- Context – Provides methods to retrieve context-specific information such as organization details, logged-in user details, or parameters that were passed to the form in a query string.
- Data – Provides access to the entity data and methods to manage the data in the form as well as in the business process flow control.
- UI – Contains methods to retrieve information about the user interface, in addition to collections for several sub-components of the form.
Objects in this model include :
- Entity – Provides methods to retrieve record information , save method , collection attributes
- Process – Methods to retrieve properties of business process flow.
- Navigation – Provides access to navigation items using items collection.
- FormSelector – Each process has a collection of stages that can be accessed using getStages method of process.
- Stages – Each process has a collection of stages that can be accessed using getStages method of process.
- Steps – Each stage comprises of various steps that can be accessed using getSteps method of stage.
Collections in this model include :
- Attributes – Provides access to entity attributes available on the form.
- Controls – ui.controls : Provides access to each control on the form ; attribute.controls : Provides access to all the controls within an attribute ; section.controls : Provides access to all the controls within a section
- Items – Provides access to all the controls within a section
- Tabs – Provides access to all the tabs on a form.
- Sections – Provides access to all the sections on a form
Supported Events in Form Programming
The Form Programming using Xrm.Page model allows you to handle the following form events :
- onLoad
- onSave
- onChange
- TabStateChange
- OnReadyStateComplete
- PreSearch
- Business Process Flow control events
Form Programming Example
In this example, we will put some validations on the Contact form based on the PreferredMethodofCommunication that the user selects. Hence, if the user selects his/her preferred method as Email, then the Email field should become mandatory and similarly for other fields of Phone and Fax.
Step 1 − Create a JavaScript file named contacts.js and copy the following code.
Step 2 − Open the Contact entity form by navigating to Settings → Customizations → Customize the System → Contact entity → Forms → Main Form.
Step 3 − Click Form Properties.
Step 4 − From the Form Properties window, click Add.
Step 5 − In the next Look Up Web Resource Record window, click New since we are creating a new web resource
Step 6 − In the New Web Resource window, enter the following details :
Name − new_contacts.js ; Display Name − contacts.js ; Type − JScript ; Upload File − Upload the JavaScript file that you created from your local machine.
Step 7 − Click Save followed by Publish. After this close the window and you will be back to Look Up Web Resource Record window.
Step 8 − Here, you can now see the new_contacts.js web resource. Select it and click Add. You have now successfully added a new web resource and registered it on the form.
Step 9 − Now we will add an event handler on the change of Preferred Method of Communication field. This event handler will call the JavaScript function that we just wrote. Select the following options from the Event Handler section.
Control − Preferred Method of Communication
Event − OnChange
Then, click the Add button, as shown in the following screenshot.
Step 10 − In the next window of Handler Properties, we will specify the method to be called when the change event occurs.
Select Library as new_contacts.js and Function as validatePreferredMethodOfCommunication. Click OK.
Step 11 − You will now be able to see the Form Library (Web Resource) and events registered on it. Click OK.
Step 12 − Click Save followed by Publish.
Step 13 − Now open any Contact form and set the Preferred Method of Communication as Phone. This will make the Mobile Phone field as mandatory. If you now try to save this contact without entering any mobile number, it will give you an error saying ‘You must provide a value for Mobile Phone’.
