SugarCRM Customization: Utilizing Custom JavaScript

SugarCRM, being a web application, naturally prompts some users to ask whether it is possible to apply customizations to the system which in turn mimic behavior they may have seen on a random web site in the course of their general web browsing. A good example would be formatting numbers entered into the phone number fields in SugarCRM, similar to the manner in which many web sites handle that type of data on a contact form.

By default, SugarCRM does not format the value one enters into any of the phone fields. For example, if one enters the value of 310.555.1212 into the Office Phone field on a contact record, it remains as such. But some users would prefer the number to be formatted, such as (310) 555-1212, or other pattern. This need gave rise to the phone formatter module that I released some years ago and made available via SugarForge.org. More importantly, it highlights the manner in which a little JavaScript code embedded within SugarCRM can be used to enrich the user experience. 

A number of other enhancements can be applied by means of custom JavaScript code, but we must first understand the manner in which it should be embedded.

Lets dissect some of the files that make up the phone formatter module to get a clearer understanding of the process one can follow to apply custom JavaScript in an upgrade-safe manner.

If you have not already done so, download the phone formatter module from SugarForge.org. We will not be installing the module, just examining some files. Thus, simply download the most current version of the module and do not concern yourself with the version of SugarCRM you are using. 

Assuming you have already downloaded it, proceed to unzip the file to a folder of your liking. Within that folder you will find the following:

File: manifest.php - Module installation instructions

Folder: ModFiles - Modified versions of SugarCRM metadata files

Folder: NewFiles - JavaScript source files (phone_format.js)

We will not be examining every file in detail, but suffice it to say that phone_format.js contains the custom JavaScript code we wish to apply to SugarCRM, while ModFiles contains the modified versions of the SugarCRM metadata files for various modules.

In our example, the formatting is applied to the value the moment the user moves the cursor away from the phone field in question. To properly apply this modification, we need two modifications within SugarCRM: first, instruct it to load the JavaScript code, and secondly, cause the phone fields to execute the code. 

To observe the manner in which the first step was completed, open the file name leads_editviewdefs.php using a text editor of your liking. It can be found in the ModFiles folder. As you can deduce from the name, it corresponds with the EditView for the Leads module. 

Sidenote: the actual name should be editviewdefs.php and would normally reside in custom/modules/Leads/metadata. It has been named leads_editviewdefs.php to more easily distinguish it from the other files the module installs. The install process will rename it to the proper name of editviewdefs.php once it is copied to the proper folder.

At line 46, you should see the following:

'includes'=> array(

                        array('file'=>'custom/include/javascript/phone_format.js'),

),

The above bit of code instructs SugarCRM to load the phone_format.js file, from the custom/include/javascript folder, whenever the EditView is accessed in the Leads module. Note that the folder does not exist by default, nor does the file. It is assumed one has already created the file and folder in advance.

Our second step, configuring the fields such that they trigger the code, or in more technical terms, defining the event for the field, is done elsewhere within the same file. 

Scrolling down to line 77 should reveal the following code:

'customCode' => '<input id="phone_work" onBlur="fmt(this.value, this.id)" name="phone_work" size="30" maxlength="25" type="text" title="{$fields.phone_work.value}" value="{$fields.phone_work.value}">',

Of utmost importance in the above line is the section that reads onBlur="fmt(this.value, this.id)" as this triggers the JavaScript code upon the user changing focus/moving cursor to a different field. In this example, the current field is the phone_work field, one of the default fields included with SugarCRM. Inspecting the definition for the other phone fields within this same file will reveal that similar code, except it will reference phone_home, phone_mobile, etc.

Through this technique, you can load your custom JavaScript and define events for the fields, in an upgrade-safe manner.