The Microsoft Dynamics CRM Blog
News and views from the Microsoft Dynamics CRM Team

Using the attachEvent method to show users context sensitive help

Using the attachEvent method to show users context sensitive help

  • Comments 7

UPDATE: This technique is actually an unsupported customization. Implementing this will place your implementation in an unsupported state. Be sure to remove this customization before calling support for any issue. 

Much of CRM is about automating processes, but your organization probably still has business processes that rely on the judgment of your workers. You train people, but you also want to make sure they have quick access to reference information to guide them if they have further questions.

In Microsoft CRM 3.0 you can provide users with specific guidance from within the Microsoft CRM form where they enter data. You can do this by programmatically adding a message that will appear to users when they put their cursor over a specific field in the form. The result can look like this:


Figure 1 – Pop-up message

This method is less obtrusive than using the JScript alert() method because users do not need to click a button to close the message. The message will disappear when the focus changes. The use of the mouseover event means that users don’t need to change the value of the field before they can see the message.

Skills required
To create this solution, you should be familiar with the following:

  • This technique uses JScript and Dynamic HTML (DHTML) to make a new field event available in the form.
  • Warning: You should have a thorough knowledge of programming syntax and logic before adding scripts, and should test your scripts before you publish customizations. Malformed scripts can prevent the form from working correctly.
  • This technique expects that you understand how to add event code to Microsoft CRM forms. For more information, see the Microsoft CRM 3.0 Online help topic, "Add an event-based script to a form."
  • You need to understand how to reference a Microsoft CRM Field using JScript. This information can be found in the Microsoft CRM SDK. See Form Properties.

Approach

Create popup object
This method uses the Microsoft CRM form Onload event to create a popup object in the document. See popup Object for more information.

Create function to show message
Define a function to display desired text for the pop-up message and call the popup.show( ) method to display the message to the user.

Note: You should specify a function name that will be unique on the form. It must not be the same as any of the default function names. This can be done by using a naming convention that includes your organization name. For example, if your organization name is Contoso, name your function Contoso_<function name>.

Attach the function to an element and an event
Finally, use the attachEvent method on a Microsoft CRM form element to make the element respond to the onmouseover event and call the function to display the message. See attachEvent Method for more information.

Note: The attachEvent method is available because Microsoft CRM is a Web application. This DHTML method is supported by Internet Explorer. However, attachEvent is not a Microsoft CRM method. Microsoft CRM Technical support does not provide support for this method. Because the use of this method isn't explicitly supported by Microsoft CRM, there is some risk that future versions of Microsoft CRM will not support the use of this method.

This approach allows for multiple event assignments for different elements of the form. Create a separate function for each event element combination. Attach each event separately.

Finally, make sure you consider the form type in your code. The element you are working with may not be included in all form types, such as the Quick Create form. Trying to attach a function to an event on an element that doesn't exist will cause an error when the form loads. You also don't want to include the message when the user cannot update the record.

Scenario
When manually entering Leads, users can select from a rating picklist field that gives them the options Hot, Warm, and Cold. It is important that these values are applied consistently. You want to provide an unobtrusive reminder of the definitions of these terms to the user while they are making their decision.

Code
The following code will display a pop-up message in the Lead form as shown in Figure 1. This code is added to the Lead form OnLoad event.

// It is a good idea to define the variables at the beginning of each event.

// This allows you to include conditional statements using the crmForm.FormType

// property.

 

var CRM_FORM_TYPE_CREATE          = 1;

var CRM_FORM_TYPE_UPDATE          = 2;

var CRM_FORM_TYPE_READ_ONLY       = 3;

var CRM_FORM_TYPE_DISABLED = 4;

var CRM_FORM_TYPE_QUICK_CREATE    = 5;

var CRM_FORM_TYPE_BULK_EDIT       = 6;

 

//Only create the pop-up message if the user can edit or update the form.

//Do not show the pop-up message in the Quick Create form.

 

switch (crmForm.FormType)

{

case CRM_FORM_TYPE_CREATE :

case CRM_FORM_TYPE_UPDATE :

case CRM_FORM_TYPE_BULK_EDIT :

 

//Create a single popup object on the form that can be re-used by

// different functions or events in the form.

       var oPopup = window.createPopup();

       var oPopupBody = oPopup.document.body;

       oPopupBody.style.backgroundColor = 'yellow';

       oPopupBody.style.fontFamily = 'Tahoma';

       oPopupBody.style.border = '1px solid black';

      

 

//Create the function that will be attached to the field mouseover event.

 

       function My_OrgName_showRatingPopup ()

       {

       // Set the message HTML.

              oPopupBody.innerHTML = "<div><table style='font-size:xx-small'>";

              oPopupBody.innerHTML += "<tr><td><b>Hot:</b></td><td> Lead has                                  expressed intention to buy our product.</td></tr>";

              oPopupBody.innerHTML += "<tr><td><b>Warm:</b></td><td> Lead is                           known to match the profile for our products.</td></tr>";

              oPopupBody.innerHTML += "<tr><td><b>Cold:</b></td><td> There is                   little or no information about the lead.</td></tr></table></div>";

       // Set the location and size of the pop-up message.

       // The x and y coordinates are relative to the form element.

              var x_coord = -100;

              var y_coord = 20;

              var width = 250;

              var height = 90;

              // Associate the pop-up message with the element where the event                  // occurred.

              var documentElement = event.srcElement;

              // Show the pop-up message.

              oPopup.show(x_coord, y_coord, width, height, documentElement);

       }

 

// Attach the onmouseover event to the field and the function.

// It is important that this be done in script after the function is defined.

 

crmForm.all.leadqualitycode.attachEvent('onmouseover', My_OrgName_showRatingPopup);

 

}

Jim Daly

  • Great tip, I've had several requests from users to add this type of functionality to our system, this is very helpful.

  • I have gotten this request a number of times. We used somethign simliar, so I am glad to see an "offical"

  • We have a requirement from client that we have the section names on the form like Section 1-Section 15 and there is a detailed explanation below the Section list. If any one wnats to see Section 5  they should click on Section 5 and the Section 5 content should come up.( basicaaly its a functionality lile linking the sections in the Same html file) how can we implement in CRM3.0

  • This javascript is going into the OnLoad event of the form, so why would it be unsupported?? Do you need to delete all of your javascript from all of the onload events before calling support? I've got onload code for some of my forms that do  AJAX calls, add "<div>" elements to the DOM, and all kinds of things that are a heck of a lot more complex than this. If I'd known they'd be unsupported, I would've saved myself a lot of hassle and simply put my shared functions into /_forms/FormAction.js

    Cheers,

    Chris

  • This works great,thanks. One thing I am seeing it requires a click for the message to disappear.  Is there a way when the mouse is moved away from the field the "tip" disappears automatically ?

    TIA.

    -G

  • Hi

    This does not work when attaching an event to an LookUp field.

    Then the srcElement.id and srcElement.DataValue is undefined....

    Any explaination or solution to this issue.?

    regards Soren

  • can anyone tell me where are the default buttons in crm 4.0 located

Page 1 of 1 (7 items)
Leave a Comment
  • Please add 4 and 2 and type the answer here:
  • Post