Add a JQuery plugin style to a SugarCRM field - Checkboxes to Switchery

This is the first 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 Switchery.  This JQuery plugin will convert normal checkboxes to iOS style buttons as shown above.   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 Switchery plugin

1. Download the plugin from here, unzip it and look int the 'dist' folder.  There you will find switchery.min.js and switchery.min.css.  I are going with the minifiyed files as I have no intention of ever editing this code, so why not.  Copy those two files to /custom/Javascript/Switchery.
2. Create the file custom/Extension/application/Ext/JSGroupings/Switchery_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.
3. The next step would be to load the CSS Loader that SugarCRM made available a few months ago.  For custom fields it is a requirement (at least the way I do it).  You only have to load this once so if you use other plugins and have already done this for them then you can skip these steps.
1. Download the Sugar Integration Building Blocks 
2. Run buildPackages.sh to zip up the example packages for upload 
3. Look for the ZIP file in packages/CssLoader/
4. Upload it to your SugarCRM instance via the Module Loader

Create the SugarCRM Custom Field Definition

Once that is done, check your permissions and you are done loading the plugin.  Now we have to create the custom SugarCRM field definition and tell it to use the plugin.  That part is even easier.

1. Find the directory clients/base/fields/bool.
2. Copy that entire directory to custom/clients/base/fields/switchery.  Make sure switchery is lower case.
3. In that directory rename bool.js to switchery.js (again remember it has to be lower case)
4. Now edit switchery.js and add this code to the header, this will add the CSS to the page for the custom buttons.
5. Now add the code that will change the checkboxes to iOS buttons.  Add this function right below the initialize() function.  It will iterate through each field and convert it (if it has not been already converted)
6. Now we have to call this function AFTER the field has been rendered.  So we edit the _render() function and add it there like this
7. Now we need to update how checkboxes in this field definition are rendered.  Edit the file custom/clients/base/fields/switchery/edit.hbs and add the code class="js-switch" to the <input> element like this
8. Then edit custom/clients/base/fields/switchery/detail.hbs and do the same line this

Updating SugarCRM with the new fields  

That is all there is to that.  Now we have a custom field definition called switchery that we can use to convert any checkbox we want.  Now we need to tell SugarCRM which checkboxes we want to modify.  In my setup I changed two checkboxes 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