Adding the Email Field to a Bean
Overview
This example explains how to add an emails field for modules that don't extend the Person module template. We will create an email field and bring the email functionality module bean. The steps are applicable for stock and custom modules. In this example, we will add the email field into the Opportunities module.
Steps to Complete
This tutorial requires the following steps, which are explained in the sections below:
- Creating a Custom Vardef file for email Field and Relationships
- Creating a Custom Bean and Modify the save function
- Replacing the stock bean with the custom bean
- Adding Emails Field into Record View
Creating a Custom Vardef file for email Field and Relationships
You will create a file in the custom/Extension/modules/Opportunities/ folder for the field and relationships definitions.
./custom/Extension/modules/Opportunities/Ext/Vardefs/custom_email_field.php
<?php
$module = 'Opportunity';
$table_name = 'opportunities';
$dictionary[$module]['fields']['email'] = array(
'name' => 'email',
'type' => 'email',
'query_type' => 'default',
'source' => 'non-db',
'operator' => 'subquery',
'subquery' => 'SELECT eabr.bean_id FROM email_addr_bean_rel eabr JOIN email_addresses ea ON (ea.id = eabr.email_address_id) WHERE eabr.deleted=0 AND ea.email_address LIKE',
'db_field' => array(
'id',
),
'vname' => 'LBL_EMAIL_ADDRESS',
'studio' => array(
'visible' => true,
'searchview' => true,
'editview' => true,
'editField' => true,
),
'duplicate_on_record_copy' => 'always',
'len' => 100,
'link' => 'email_addresses_primary',
'rname' => 'email_address',
'module' => 'EmailAddresses',
'full_text_search' => array(
'enabled' => true,
'searchable' => true,
'boost' => 1.50,
),
'audited' => true,
'pii' => true,
);
$dictionary[$module]['fields']['email1'] = array(
'name' => 'email1',
'vname' => 'LBL_EMAIL_ADDRESS',
'type' => 'varchar',
'function' => array(
'name' => 'getEmailAddressWidget',
'returns' => 'html',
),
'source' => 'non-db',
'link' => 'email_addresses_primary',
'rname' => 'email_address',
'group' => 'email1',
'merge_filter' => 'enabled',
'module' => 'EmailAddresses',
'studio' => false,
'duplicate_on_record_copy' => 'always',
'importable' => false,
);
$dictionary[$module]['fields']['email2'] = array(
'name' => 'email2',
'vname' => 'LBL_OTHER_EMAIL_ADDRESS',
'type' => 'varchar',
'function' => array(
'name' => 'getEmailAddressWidget',
'returns' => 'html',
),
'source' => 'non-db',
'group' => 'email2',
'merge_filter' => 'enabled',
'studio' => 'false',
'duplicate_on_record_copy' => 'always',
'importable' => false,
'workflow' => false,
);
$dictionary[$module]['fields']['invalid_email'] = array(
'name' => 'invalid_email',
'vname' => 'LBL_INVALID_EMAIL',
'source' => 'non-db',
'type' => 'bool',
'link' => 'email_addresses_primary',
'rname' => 'invalid_email',
'massupdate' => false,
'studio' => 'false',
'duplicate_on_record_copy' => 'always',
);
$dictionary[$module]['fields']['email_opt_out'] = array(
'name' => 'email_opt_out',
'vname' => 'LBL_EMAIL_OPT_OUT',
'source' => 'non-db',
'type' => 'bool',
'link' => 'email_addresses_primary',
'rname' => 'opt_out',
'massupdate' => false,
'studio' => 'false',
'duplicate_on_record_copy' => 'always',
);
$dictionary[$module]['fields']['email_addresses_primary'] = array(
'name' => 'email_addresses_primary',
'type' => 'link',
'relationship' => strtolower($table_name) . '_email_addresses_primary',
'source' => 'non-db',
'vname' => 'LBL_EMAIL_ADDRESS_PRIMARY',
'duplicate_merge' => 'disabled',
'primary_only' => true,
);
$dictionary[$module]['fields']['email_addresses'] = array(
'name' => 'email_addresses',
'type' => 'link',
'relationship' => strtolower($table_name) . '_email_addresses',
'source' => 'non-db',
'vname' => 'LBL_EMAIL_ADDRESSES',
'reportable' => false,
'unified_search' => true,
'rel_fields' => array('primary_address' => array('type' => 'bool')),
);
// Used for non-primary mail import
$dictionary[$module]['fields']['email_addresses_non_primary'] = array(
'name' => 'email_addresses_non_primary',
'type' => 'varchar',
'source' => 'non-db',
'vname' => 'LBL_EMAIL_NON_PRIMARY',
'studio' => false,
'reportable' => false,
'massupdate' => false,
);
$dictionary[$module]['relationships'][strtolower($table_name) . '_email_addresses'] = array(
'lhs_module' => $table_name,
'lhs_table' => strtolower($table_name),
'lhs_key' => 'id',
'rhs_module' => 'EmailAddresses',
'rhs_table' => 'email_addresses',
'rhs_key' => 'id',
'relationship_type' => 'many-to-many',
'join_table' => 'email_addr_bean_rel',
'join_key_lhs' => 'bean_id',
'join_key_rhs' => 'email_address_id',
'relationship_role_column' => 'bean_module',
'relationship_role_column_value' => $table_name,
);
$dictionary[$module]['relationships'][strtolower($table_name) . '_email_addresses_primary'] = array(
'lhs_module' => $table_name,
'lhs_table' => strtolower($table_name),
'lhs_key' => 'id',
'rhs_module' => 'EmailAddresses',
'rhs_table' => 'email_addresses',
'rhs_key' => 'id',
'relationship_type' => 'many-to-many',
'join_table' => 'email_addr_bean_rel',
'join_key_lhs' => 'bean_id',
'join_key_rhs' => 'email_address_id',
'relationship_role_column' => 'bean_module',
'relationship_role_column_value' => $module,
'primary_flag_column' => 'primary_address',
);
Creating a Custom Bean and Modifying the Save Function
Next step, you will need to create a custom bean that extends from the stock bean. In our example, we choose the Opportunities.
./custom/modules/Opportunities/CustomOpportunity.php
<?php
class CustomOpportunity extends Opportunity
{
/**
* Constructor
*/
public function __construct()
{
parent::__construct();
$this->emailAddress = BeanFactory::newBean('EmailAddresses');
}
/**
* Populate email address fields here instead of retrieve() so that they are properly available for logic hooks
*
* @see parent::fill_in_relationship_fields()
*/
public function fill_in_relationship_fields()
{
parent::fill_in_relationship_fields();
$this->emailAddress->handleLegacyRetrieve($this);
}
/**
* @see parent::get_list_view_data()
*/
public function get_list_view_data()
{
global $current_user;
$temp_array = $this->get_list_view_array();
$temp_array['EMAIL'] = $this->emailAddress->getPrimaryAddress($this);
// Fill in the email1 field only if the user has access to it
// This is a special case, because getEmailLink() uses email1 field for making the link
// Otherwise get_list_view_data() shouldn't set any fields except fill the template data
if ($this->ACLFieldAccess('email1', 'read')) {
$this->email1 = $temp_array['EMAIL'];
}
$temp_array['EMAIL_LINK'] = $current_user->getEmailLink('email1', $this, '', '', 'ListView');
return $temp_array;
}
/**
*
* @see parent::save()
*/
public function save($check_notify = false)
{
if (static::inOperation('saving_related')) {
parent::save($check_notify);
return $this;
}
$ori_in_workflow = empty($this->in_workflow) ? false : true;
$this->emailAddress->handleLegacySave($this, $this->module_dir);
parent::save($check_notify);
$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)) {
$result = $this->emailAddress->save($this->id, $this->module_dir, $override_email, '', '', '', '',
$this->in_workflow);
}
return $this;
}
}
Replacing the Stock Bean with a Custom Bean
Once you created the custom bean, you will need to show Sugar to use Custom bean. To do that you will create ./custom/modules/<modulename>/<modulename>.php and update the class name and file path in the $beanList and $beanFiles. (See: Modules $beanList and Customizing Core SugarBeans)
custom/Extension/application/Ext/Include/customOpportunities.php
<?php
$objectList['Opportunities'] = 'Opportunity';
$beanList['Opportunities'] = 'CustomOpportunity';
$beanFiles['CustomOpportunity'] = 'custom/modules/Opportunities/CustomOpportunity.php';
Once you have created these files, you will need to navigate Admin > Repairs and perform Quick Repair and Rebuild.
Adding the Emails Field to the Record View
At the stage, you have already created the field and updated the bean. The last step is placing the email field to record view. You can perform this step using Studio. Once you navigate to Studio you will find an Email field on the left column where available fields are listed. After adding the field the record views of Opportunities will look like this:
./custom/modules/Opportunities/clients/base/views/record/record.php
<?php
$viewdefs['Opportunities'] =
array (
'base' =>
array (
'view' =>
array (
'record' =>
array (
'buttons' =>
array (
0 =>
array (
'type' => 'button',
'name' => 'cancel_button',
'label' => 'LBL_CANCEL_BUTTON_LABEL',
'css_class' => 'btn-invisible btn-link',
'showOn' => 'edit',
'events' =>
array (
'click' => 'button:cancel_button:click',
),
),
1 =>
array (
'type' => 'rowaction',
'event' => 'button:save_button:click',
'name' => 'save_button',
'label' => 'LBL_SAVE_BUTTON_LABEL',
'css_class' => 'btn btn-primary',
'showOn' => 'edit',
'acl_action' => 'edit',
),
2 =>
array (
'type' => 'actiondropdown',
'name' => 'main_dropdown',
'primary' => true,
'showOn' => 'view',
'buttons' =>
array (
0 =>
array (
'type' => 'rowaction',
'event' => 'button:edit_button:click',
'name' => 'edit_button',
'label' => 'LBL_EDIT_BUTTON_LABEL',
'acl_action' => 'edit',
),
1 =>
array (
'type' => 'shareaction',
'name' => 'share',
'label' => 'LBL_RECORD_SHARE_BUTTON',
'acl_action' => 'view',
),
2 =>
array (
'type' => 'pdfaction',
'name' => 'download-pdf',
'label' => 'LBL_PDF_VIEW',
'action' => 'download',
'acl_action' => 'view',
),
3 =>
array (
'type' => 'pdfaction',
'name' => 'email-pdf',
'label' => 'LBL_PDF_EMAIL',
'action' => 'email',
'acl_action' => 'view',
),
4 =>
array (
'type' => 'divider',
),
5 =>
array (
'type' => 'rowaction',
'event' => 'button:find_duplicates_button:click',
'name' => 'find_duplicates_button',
'label' => 'LBL_DUP_MERGE',
'acl_action' => 'edit',
),
6 =>
array (
'type' => 'rowaction',
'event' => 'button:duplicate_button:click',
'name' => 'duplicate_button',
'label' => 'LBL_DUPLICATE_BUTTON_LABEL',
'acl_module' => 'Opportunities',
'acl_action' => 'create',
),
7 =>
array (
'type' => 'rowaction',
'event' => 'button:historical_summary_button:click',
'name' => 'historical_summary_button',
'label' => 'LBL_HISTORICAL_SUMMARY',
'acl_action' => 'view',
),
8 =>
array (
'type' => 'rowaction',
'event' => 'button:audit_button:click',
'name' => 'audit_button',
'label' => 'LNK_VIEW_CHANGE_LOG',
'acl_action' => 'view',
),
9 =>
array (
'type' => 'divider',
),
10 =>
array (
'type' => 'rowaction',
'event' => 'button:delete_button:click',
'name' => 'delete_button',
'label' => 'LBL_DELETE_BUTTON_LABEL',
'acl_action' => 'delete',
),
),
),
3 =>
array (
'name' => 'sidebar_toggle',
'type' => 'sidebartoggle',
),
),
'panels' =>
array (
0 =>
array (
'name' => 'panel_header',
'header' => true,
'fields' =>
array (
0 =>
array (
'name' => 'picture',
'type' => 'avatar',
'size' => 'large',
'dismiss_label' => true,
'readonly' => true,
),
1 =>
array (
'name' => 'name',
'related_fields' =>
array (
0 => 'total_revenue_line_items',
1 => 'closed_revenue_line_items',
2 => 'included_revenue_line_items',
),
),
2 =>
array (
'name' => 'favorite',
'label' => 'LBL_FAVORITE',
'type' => 'favorite',
'dismiss_label' => true,
),
3 =>
array (
'name' => 'follow',
'label' => 'LBL_FOLLOW',
'type' => 'follow',
'readonly' => true,
'dismiss_label' => true,
),
),
),
1 =>
array (
'name' => 'panel_body',
'label' => 'LBL_RECORD_BODY',
'columns' => 2,
'labels' => true,
'labelsOnTop' => true,
'placeholders' => true,
'newTab' => false,
'panelDefault' => 'expanded',
'fields' =>
array (
0 =>
array (
'name' => 'account_name',
'related_fields' =>
array (
0 => 'account_id',
),
),
1 =>
array (
'name' => 'date_closed',
'related_fields' =>
array (
0 => 'date_closed_timestamp',
),
),
2 =>
array (
'name' => 'amount',
'type' => 'currency',
'label' => 'LBL_LIKELY',
'related_fields' =>
array (
0 => 'amount',
1 => 'currency_id',
2 => 'base_rate',
),
'currency_field' => 'currency_id',
'base_rate_field' => 'base_rate',
'span' => 12,
),
3 =>
array (
'name' => 'best_case',
'type' => 'currency',
'label' => 'LBL_BEST',
'related_fields' =>
array (
0 => 'best_case',
1 => 'currency_id',
2 => 'base_rate',
),
'currency_field' => 'currency_id',
'base_rate_field' => 'base_rate',
),
4 =>
array (
'name' => 'worst_case',
'type' => 'currency',
'label' => 'LBL_WORST',
'related_fields' =>
array (
0 => 'worst_case',
1 => 'currency_id',
2 => 'base_rate',
),
'currency_field' => 'currency_id',
'base_rate_field' => 'base_rate',
),
5 =>
array (
'name' => 'tag',
'span' => 6,
),
6 =>
array (
'name' => 'sales_status',
'readonly' => true,
'studio' => true,
'label' => 'LBL_SALES_STATUS',
'span' => 6,
),
7 =>
array (
'name' => 'email',
'studio' =>
array (
'visible' => true,
'searchview' => true,
'editview' => true,
'editField' => true,
),
'label' => 'LBL_EMAIL_ADDRESS',
'span' => 12,
),
),
),
2 =>
array (
'name' => 'panel_hidden',
'label' => 'LBL_RECORD_SHOWMORE',
'hide' => true,
'labelsOnTop' => true,
'placeholders' => true,
'columns' => 2,
'newTab' => false,
'panelDefault' => 'expanded',
'fields' =>
array (
0 => 'next_step',
1 => 'opportunity_type',
2 => 'lead_source',
3 => 'campaign_name',
4 =>
array (
'name' => 'description',
'span' => 12,
),
5 => 'assigned_user_name',
6 => 'team_name',
7 =>
array (
'name' => 'date_entered_by',
'readonly' => true,
'type' => 'fieldset',
'label' => 'LBL_DATE_ENTERED',
'fields' =>
array (
0 =>
array (
'name' => 'date_entered',
),
1 =>
array (
'type' => 'label',
'default_value' => 'LBL_BY',
),
2 =>
array (
'name' => 'created_by_name',
),
),
),
8 =>
array (
'name' => 'date_modified_by',
'readonly' => true,
'type' => 'fieldset',
'label' => 'LBL_DATE_MODIFIED',
'fields' =>
array (
0 =>
array (
'name' => 'date_modified',
),
1 =>
array (
'type' => 'label',
'default_value' => 'LBL_BY',
),
2 =>
array (
'name' => 'modified_by_name',
),
),
),
),
),
),
'templateMeta' =>
array (
'useTabs' => false,
),
),
),
),
);
Once the files are in place, navigate to Admin > Repair > Quick Repair & Rebuild to regenerate the metadata.