HOWTO: Add an email address widget to any module

Matthew Marum —  August 8, 2011 — 19 Comments

If you build a new module thru Module Builder that is of the Person or Company type, you automatically will get an email address field as one of the default fields in the module. But if you are building off a different template, or building a module by hand? The email address field in Sugar is a bit more complicated, since it ties into the main database of all of the email addresses in your Sugar instance to help manage opt-out and invalid email settings in one place when an email address is used across different records and modules. Here’s how to add it to your module:

The first part is to add the needed fields and relationships to your module. The most upgrade-safe way to do this is by adding a new file named emailaddress.php to the custom/Extension/modules/YOURMODULENAME/Ext/Vardefs/ directory with the following contents:


$dictionary[$module]['fields']['email1'] = array(
    'name'        => 'email1',
    'vname'        => 'LBL_EMAIL',
    'type'        => 'varchar',
    'function'    => array(
    'name'        => 'getEmailAddressWidget',
       'returns'    => 'html'
    'source'    => 'non-db',
    'studio' => array('editField' => true),

$dictionary[$module]['fields']['email_addresses_primary'] = array(
    'name' => 'email_addresses_primary',
    'type' => 'link',
    'relationship' => strtolower($module).'_email_addresses_primary',
    'source' => 'non-db',
    'duplicate_merge' => 'disabled',

$dictionary[$module]['fields']['email_addresses'] = array (
    'name' => 'email_addresses',
    'type' => 'link',
    'relationship' => strtolower($module).'_email_addresses',
    'source' => 'non-db',
    'vname' => 'LBL_EMAIL_ADDRESSES',
    'unified_search' => true,
    'rel_fields' => array('primary_address' => array('type'=>'bool')),

$dictionary[$module]['relationships'][strtolower($module).'_email_addresses'] = array(
    'lhs_module'=> $module,
    'lhs_table'=> strtolower($module),
    'lhs_key' => 'id',
    'rhs_module'=> 'EmailAddresses',
    'rhs_table'=> 'email_addresses',
    'rhs_key' => 'id',
    'join_table'=> 'email_addr_bean_rel',

$dictionary[$module]['relationships'][strtolower($module).'_email_addresses_primary'] = array(
    'lhs_module'=> $module,
    'lhs_table' => strtolower($module),
    'lhs_key' => 'id',
    'rhs_module' => 'EmailAddresses',
    'rhs_table' => 'email_addresses',
    'rhs_key' => 'id',
    'join_table'=> 'email_addr_bean_rel',

You’ll need to do a quick rebuild and repair to make the email field available in your module after adding this file.

Next, we need to add the save and retrieve code for your module into the bean file. If you are adding this to your own created module or one you built thru Module Builder then this is upgrade-safe; if you are editing an out of the box module then this is not upgrade-safe. You’ll need to modify the bean’s constructor, save, and retrieve methods as shown below:

class MYMODULECLASS extends SugarBean

	public function __construct()
		$this->emailAddress = new SugarEmailAddress();

	public function retrieve($id = -1, $encode=true)
		$ret_val = parent::retrieve($id, $encode);
		return $ret_val;

	public function save($check_notify=false)
		$ori_in_workflow = empty($this->in_workflow) ? false : true;
		$this->emailAddress->handleLegacySave($this, $this->module_dir);
        	$override_email = array();
        	if(!empty($this->email1_set_in_workflow)) {
        	    $override_email['emailAddress0'] = $this->email1_set_in_workflow;
        	if(!empty($this->email2_set_in_workflow)) {
        	    $override_email['emailAddress1'] = $this->email2_set_in_workflow;
        	if(!isset($this->in_workflow)) {
        	    $this->in_workflow = false;
        	if($ori_in_workflow === false || !empty($override_email)){
        	    $this->emailAddress->save($this->id, $this->module_dir, $override_email,'','','','',$this->in_workflow);
		return $this->id;

With that, the email address field should be available on your module.

Matthew Marum


Matt is the Director of Developer Advocacy for SugarCRM. Previously he was an Engineer on Sugar 7 and a Solutions Architect for the OEM program. He is also an avid trail runner, Boston Marathon qualifier and a karaoke aficionado.

19 responses to HOWTO: Add an email address widget to any module



    Thanks very much for this! Just a quick question; I’m adding this to a module built via the Module Builder. Do I need to carry out the second part (adding the ‘extends SugarBean’ code)? If so, whereabouts would I add this?

    Thanks again, this post was timed perfectly for what I’m trying to do!


      If you are building with Module Builder, you can add these methods in that section to the modulename.php file in the deployed module directory.


        Thanks for this solution.

        Extending James’ point.. I am trying to derive this feature to add and append ‘Miscellaneous notes’ to a custom module. Should I simply repeat the steps you mentioned and just modify the relationship table names in the first part (to something like ‘misc_notes’ and ‘misc_note_bean_rel’ respectively)? Or does it require a different level of effort/work altogether? Please advise.


    The email is not getting displayed on the list view and the subpanels.
    I followed all the steps shown here, not sure what I missed.Please advice.


    I take it this isn’t something that shows up in “Studio”… so I’m going to have to just create the field by hand of that type, correct?  Any code snippet I can steal out of lazyness?


       This is something that you have to code by hand unfortunately, but would probably be a good thing to have Studio able to add. Please add a bug for this at Thanks!


        Ok I filed that bug!  However, my original question was unclear – What I meant was, once I use the above code (which I have implemented verbatim (changing my module name of course)), does the new field appear in the layout options in Studio?  I’ve run multiple repair / rebuilds and I still don’t see where those fields are.  
        Sorry for all the hand-holding John!! =)


           The field should be available in Studio to move around, yes. You may need to add it to the detailviewdefs.php file first if it’s not in the list of available fields by default.


    And what if I want to create a new field called “websites” with the same multi entries feature as email. Do I need to create a new Table “websites” and a “websites_rel” to relate it to a contact for example?


      I think you could probably get away with one table versus two, just depending upon your requirements. The main reason we have the extra join table in there for emails is so that we can easily manage the opt-out and invalid status across records, which may or may not be an issue for the websites field you propose.


        Thanks for this solution.

        Extending Juan’s point.. I am trying to derive this feature to add and append ‘Miscellaneous notes’ to a custom module. Should I simply repeat the steps you mentioned and just modify the relationship table names in the first part (to something like ‘misc_notes’ and ‘misc_note_bean_rel’ respectively)? Or does it require
        a different level of effort/work altogether? Please advise.

        (Sorry if this is a repost)


    After using code i am getting email address hyper inked but it not taking me to email compose box somehow it taking me to the domain name address directly .Please help i have not change any relationship in the present code


    I have some problems adding the second code. I don’t know exactly where to do it. I’ve tried several times with different alternatives but I got different kind of errors everytime. Any help please.


    Is this still working for 6.5.16 CE? I followed all the steps, but the relation is not loading for me. I see no data in my subpanels/detailviews and also have no additional information in my debug-log.


    how it can be done in SugarCRM Professional 7.5.x?


    Just follow the link below. Hopefully you will find your Solution.


    well those codes are not working in sugar free version ….

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s