Add a JQuery plugin style to a SugarCRM field - Phone Fields to jQuery-mask

This is the second in a series where I will show ways to add JQuery custom UI elements to SugarCRM views.   This is fairly easy to do for most JQuery plugins.

In this post we are going to use jQuery-mask.  This JQuery plugin will convert normal text fields to masked input fields where the input is dynamically formatted as the user types it in.  For example you can do phone numbers, IP addresses, Money or percents.   It has a few options but in this first part we are just going to stick to the defaults.  First we have to get the plugin loading into SugarCRM.  We could use the JS loader plugin they released a while back but I had issues with that loading the script multiple times so we are going to stick to the tried and true JSGroupings for this one.

Considerations: 

1. The full code for this modification is available at the bottom of this post for those who don't want to follow step by step.  I wouldn't either, the steps are really just to learn the process I took to make this modification so you might try to make your own.
2. This post assumes you have a minimum level of programming experience.  I try to be as plain as I can be but if you have never touched an editor before maybe you should ask around and find someone to do this for you.  It is insanely easy to completely botch things up. 
3. This post DOES NOT cover adding this modification to Studio.  Any field you modify with this code wil work 100% in studio but you will not be able to add a new field with this modifiction already in place.  You will have to add a checkbox and then modify the PHP manually.  I will get to making a post on how to make a fully realized custom field definition that is avaialble in Studio but not this time.

Loading the jQuery-mask plugin

1. Download the plugin from here, unzip it and look int the 'dist' folder.  There you will find jquery.mask.js.  Copy this file to /custom/Javascript/jQuery-Mask.
2. Create the file custom/Extension/application/Ext/JSGroupings/jQuery-mask_grouping.php.  This will hold our addition to the JSGroupings.  Look here if you need information on what JSGroupings is.  This is what the contents of this file should be.

Create the SugarCRM Custom Field Definition

Once that is done, we have to create the custom SugarRM field definition.  That part is even easier.

1. Find the directory clients/base/fields/phone.
2. Copy that entire directory to custom/clients/base/fields/masked-phone.  Make sure 'masked-phone' is lower case.
3. In that directory rename phone.js to masked-phone.js (again remember it has to be lower case)
4. Now edit masked-phone.js and add this code that will change the phone number field to a masked verison.   Add this function right below the initialize() function.  It will enable each phone field as it is rendered and define the phone number mask.  As you can see I added code so that if there are fewer than 8 numbers it uses one mask and if there are more than 8 numbers it changes the mask to include area code.
5. Now we need to update how the phone numbers in this field definition are rendered.  Edit the file custom/clients/base/fields/masked-phone/edit.hbs and add the code class "phone_us" to the <input> element.  To do that you must look for the code that looks like this  class="inherit-width" and change it to this class="inherit-width phone_us"
6. Then edit custom/clients/base/fields/switchery/detail.hbs and do the same thing as above

Updating SugarCRM with the new fields  

That is all there is to that.  Now we have a custom field definition called masked-phone that we can use to convert any phone field we want.  Now we need to tell SugarCRM which phone fields we want to modify.  In my setup I changed two phone fields in Accounts by editing the file custom/modules/Accounts/clients/base/views/record/record.php.  I simply added a 'type' element to the array for the fields I wanted to change like this
You will also have to update the create.php if you have one.  Once that is done, all you have to do is run a

1. Quick Repair and Rebuild 
2. Rebuild JS Groupings
3. Another Quick Repair and Rebiold
4. Start using the fields.

As Promised

Here is a link to all the files