Creating a reusable script button for Dynamics CRM

In this post, I provide instructions on how to build a reusable CRM entity form button that execute JavaScript code.

On a CRM entity form, there is often the need to embed a custom HTML web resource button instead of using a custom ribbon button. There may be the need to have multiple buttons on the same entity form or buttons on multiple entities. The approach discussed here, will allow you to create one HTML button solution and re-use it multiple times on the same form or with different CRM entity forms as needed.

I will use the standard CRM Contact entity as an example as shown below;

At the bottom of the image is a rectangular white button with the text ‘Test Me’. This is the custom button, a CRM HTML Web Resource embedded on this form. When you move your mouse over the button, it changes to a light blue color and a tooltip is displayed as shown below;

When you click on the button, it executes form JavaScript and displays a test message. The action taken here, is just a brief example, you would build out your own script as needed wherever the button is implemented.

Let’s get started

To create a reusable button, we need to create a button that accepts predefined parameters. At a minimum, you would need to provide the following:

  • A unique button name, which will be used to identify what script to execute.
  • The text to be displayed as a tooltip when the user move their mouse over the button.
  • The text to display permanently on the button.

You can of course extend these parameters as needed for your own specific needs. The required parameters are provided when you add the script button web resource to your CRM form.

Using a developer platform such as Visual Studio, create a solution that supports HTML and JavaScript web development.

Visual Studio Solution

I will be using an existing an existing project, where I add a new folder called ‘CRM2015_ScriptButton’.
Within this new folder I create a ‘css’ and a ‘js’ folder, as shown below;

We will create four web resources:

  • CRM2015_ScriptButtonStyle.css
  • ContactFormScriptTest.js
  • CRM2015_ScriptButton_ScriptLib.js
  • CRM2015_ScriptButton.html

Creating the CRM2015_ScriptButtonStyle.css file

Add the new ‘CRM2015_ScriptButtonStyle.css’ file in the ‘css’ sub-folder within the ScriptButton’ folder.
Add the content shown below to the css file, further details will follow:

body {
}
.DefaultForm {
    margin: 0px;
    border: 0px;
    background-color: White;
    font-family: Arial, Helvetica, sans-serif;
    font-size:75%;
}
.CrmButton {
background-color: rgb(255,255,255);
background-image: none;
background-repeat: repeat-x;
border-bottom-color: rgb(198,198,198);
border-bottom-style: solid;
border-bottom-width: 1px;
border-left-color: rgb(198,198,198);
border-left-style: solid;
border-left-width: 1px;
border-right-color: rgb(198,198,198);
border-right-style: solid;
border-right-width: 1px;
border-top-color: rgb(198,198,198);
border-top-style: solid;
border-top-width: 1px;
color: rgb(68,68,68);
direction: ltr;
font-family: 'Segoe UI',Tahoma,Arial;
font-size: 14px;
height: 30px;
line-height: 16px;
margin-left: 8px;
margin-top: 5px;
min-width: 100px;
padding-left: 5px;
padding-right: 5px;
text-align: center;
white-space: nowrap;
cursor: not-allowed;
}

.CrmButton:hover:enabled
{
    background-color: rgba(177,214,240,1);
    cursor: pointer;
}

The css source code above contains the style applied to the button that provide the current look and feel. If you would like to achieve a different look and feel, you can make the necessary changes here.

Creating the ContactFormScriptTest.js file

Add the new ‘ContactFormScriptTest.js’ file in the ‘js’ sub-folder within the ScriptButton’ folder.
Add the content shown below to the js file, further details will follow:

//ContactFormScriptTest.js

function crmXtra_buttonAction(crmXtra_buttonName) {
    try {
        //Script button clicked, determine action based on button name
        if (crmXtra_buttonName == "ScriptButtonTest") {
            alert("You clicked on a button named '" + crmXtra_buttonName + "' on " + Xrm.Page.getAttribute("fullname").getValue() + "'s CRM contact form!");
        }
        else {
            alert("The Script button named '" + crmXtra_buttonName + "' has not been defined.");
        }
    }
    catch (err) {
        alert('crmXtra Script Button Function Error(crmXtra_buttonAction): ' + err.message);
    }
}

The source code above contains the function ‘crmXtra_buttonAction’. This script is added as form script on the CRM entity form where the button is implemented. You will modify this script to have the necessary functionality that your button will need.
This function has a parameter passed to it with the name of the button that was clicked on, so you will write your code to handle each button that you placed on your CRM entity form based on the button name.

Creating the CRM2015_ScriptButton_ScriptLib.js file

Add the new ‘CRM2015_ScriptButton_ScriptLib.js’ file in the ‘js’ sub-folder within the ScriptButton’ folder.
Add the content shown below to the js file, further details will follow:

//CRM2015_ScriptButton_ScriptLib.js

var crmXtra_query = "";

function crmXtra_formLoad() {
    try {
        //Initialize content
        crmXtra_query = decodeURI(window.location.search.substring(1));  //Get Query URL
        var crmXtra_queryArray = crmXtra_query.split("&");  //Remove non data element
        crmXtra_query = crmXtra_queryArray[0];
        //Get the button name, title (tooltip), value (buttontext)  (The name should not have spaces or special characters).
        //Format is Name~~Title~~Value  as a text string
        crmXtra_query = crmXtra_query.replace("data=", "");
        crmXtra_query = crmXtra_query.split("~~");
        //Verify array length of 3
        if (crmXtra_query.length != 3) {
            alert("The Script button definition of '" + crmXtra_query + "' is undefined, please update your web resource data, to have a button name, tooltip text and button text, separated by '~~'.");
            //Disable button and set text to UNDEFINED ACTION
            document.getElementById('btnAction').disabled = true;
            document.getElementById("btnAction").value = "*UNDEFINED ACTION*";
            return false;
        }
        //Disable button if entity form is read only
        if (parent.Xrm.Page.ui.getFormType() >= 3) {
            document.getElementById('btnAction').disabled = true;
        }
        //Set button title/tooltip, value/text
        document.getElementById("btnAction").title = crmXtra_query[1];
        document.getElementById("btnAction").value = crmXtra_query[2];
    }
    catch (err) {
        alert('Button Control Script Function Error(crmXtra_formLoad): ' + err.message);
    }
}

function crmXtra_buttonClick() {
    try {
        //Call related function on parent form
        parent.crmXtra_buttonAction(crmXtra_query[0]);
    }
    catch (err) {
        alert('Button Control Script Function Error(crmXtra_buttonClick): ' + err.message);
    }
}

The script above contains two functions, crmXtra_formLoad and crmXtra_buttonClick.

The crmXtra_formLoad function executes when the ScriptButton HTML page loads. It first extracts the query values passed from the CRM entity page and splits up its data portion into the button name, tooltip and button text. You will notice two ‘~’ tilde symbols used in the code to extract these into the three values needed. ‘~~’ is simply used to easily separate these values and has no other use in this context.
The state of the CRM entity form is also checked here and if it is at a read-only state, then the button will render as disabled.
The tooltip and button text is also applied here. If these values are missing, the button will be disabled and displayed as “UNDEFINED ACTION”.

The crmXtra_buttonClick function is used to call the ‘crmXtra_buttonAction’ function on the entity form. The name of the button is passed to the function in the ‘ContactFormScriptTest.js’ script library discussed earlier.

Creating the CRM2015_ScriptButton.html file

Add the new ‘CRM2015_ScriptButton.html’ file in the ScriptButton’ folder.
Add the content shown below to the html file, further details will follow:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>crmXtra Button</title>
    <!-- Button Control Custom Stylesheet -->
    <link href="css/CRM2015_ScriptButtonStyle.css" rel="stylesheet" />
    <!--Control Library /-->
    <script type="text/javascript" src="js/CRM2015_ScriptButton_ScriptLib.js"></script>
</head>
<body class="DefaultForm" tabindex="0">
    <div id="crmXtraButton" style="text-align:center;">
        <input id="btnAction" type="button" class="CrmButton" value="" title="" onclick="crmXtra_buttonClick();"/>
    </div>
    <script type="text/javascript">
        window.onload = function () {
            //Actions/Functions to execute as soon as the form is loaded
            try {
                //Initialize the button
                crmXtra_formLoad();
            }
            catch (err) {
                //Display Error....
                alert('CRM2015_ScriptButton.html Script Document Ready Error: ' + err.message);
            }
        };
    </script>
</body>
</html>

The source code listed above renders the custom script button as an HTML web resource in CRM.

Your Visual Studio folder, should now look something like;

Adding your Web Resource project to CRM

Within CRM, select an existing solution or create a new solution to add your web resource files to.

Add your files as shown in the next screenshots;
(Click image to view larger size)

/crmXtra_Samples/CRM2015_ScriptButton/css/CRM2015_ScriptButtonStyle.css

/crmXtra_Samples/CRM2015_ScriptButton/js/ContactFormScriptTest.js

/crmXtra_Samples/CRM2015_ScriptButton/js/CRM2015_ScriptButton_ScriptLib.js

/crmXtra_Samples/CRM2015_ScriptButton/CRM2015_ScriptButton.html

Adding a button to a CRM entity form

In order to add one or multiple script buttons to an entity form, you must first add the ‘ContactFormScriptTest.js’ or similar resource to the entity form. For example to add a button to the Contact form do the following:

Open the contact entity form in design mode as shown below:

Click on the ‘Form Properties’ button, you should see:

Click on the Add button and search for ‘crmxtra_/crmXtra_Samples/CRM2015_ScriptButton/js/ContactFormScriptTest.js’ or similar and add it. You should then see something like:

Click ‘OK’ to save and return to the contact form in design mode.

Locate an area on the form, where you would like the script button to appear. The button’s width will vary depending upon the text/label it displays, so take that into consideration. The button will typically require a height of 2 CRM rows. Use the ‘Insert’ tab and ‘Web Resource’ to add the new button.

Search for the web resource named ‘crmxtra_/crmXtra_Samples/CRM2015_ScriptButton/CRM2015_ScriptButton.html’ or similar. Fill in the information requested as follows:

You can name the web resource button anything you want as long as it is unique to this form. The custom parameter (data) field is where you enter the parameters to pass to the button when it is initialized.
The sample shown has: ScriptButtonTest~~Click here to test the script button~~Test Me
Again, the ‘~~’ is simply a separator, so that our split command elsewhere will break the string into its three values, consisting of:

  • A unique button name, which will be used to identify what script to execute.
  • The text to be displayed as a tooltip when the user move their mouse over the button.
  • The text to display permanently on the button.

Next, we need to set the formatting tab. Typically I would set it as follows:

Click ‘OK’ followed by a ‘Save’ and Publish of the form.

Testing your entity form script button

To try out the button and provided you used the Contact entity as described, simply open a CRM Contact entity record. The button you created should be visible, mouse over to see it change color and display the tooltip and click to execute the button click action script.