The document discusses best practices for customizing SugarCRM applications. It recommends using Module Builder/Studio for customizations when possible, and placing any custom code in the custom directory to keep it separate from core code and prevent upgrades from overwriting changes. It also covers SugarCRM's MVC framework, metadata definitions, logic hooks, themes, and where to place custom code for each.

1. 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 1

2. Best Practices for Creating Custom Apps in Sugar John Mertic SugarCRM 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 2

3. The golden rules of customizations Use Module Builder/Studio for customizations if possible Otherwise, put your code inside the custom directory 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 3

4. Why do this? Module Builder/Studio changes are well supported and easier to manage Customizations are separated from the shipped code Allows you to manage your customizations via version control ( SVN, Git, etc ) Files in here aren’t disturbed by any Sugar upgrades Exception – sometimes we will try to fix metadata templates on upgrades for new/removed fields. Makes your app “Upgrade Safe” 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 4

5. Exceptions to this… New modules need to be under modules/ directory. Bean class customizations to OOTB modules need to be on the original bean file. We’ll look at using logic hooks and other techniques to avoid this for many use cases. Will need to manually manage this during upgrades, so best to avoid. 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 5

6. Let’s see what we can do 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 6

7. MVC Framework MVC stands for Model View Controller 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 7

8. MVC Framework – The anatomy of a request 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 8

9. MVC Framework – SugarApplication Bootstraps the application Loads many of the default application settings Language Theme Session Handles User Authentication Loads the controller 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 9

10. MVC Framework - SugarController Manages all the actions of a module Contains logic for handling requests that don’t require a view Example: Record saving Maps all other requests to the correct view Logic for mapping an action of one name to a view of another Can detect if we should be using MVC or classic views 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 10

11. MVC Framework – SugarController API 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 11

12. MVC Framework – Controller Example 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 12 <?php class ExampleController extends SugarController { public function action_hello() { echo "Hello World!"; } public function action_goodbye() { $this->view = 'goodbye'; } }

13. MVC Framework – Controller-less mapping If your module doesn’t need to have any controller logic, use action mapping insteads. Create file named action_view_map.php with the following contents: 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 13 <?php $action_view_map['goodbye'] = 'goodbye';

14. MVC Framework - SugarView Contains the display logic for the action Uses a metadata backend for Edit, Detail, List, Popup views And Convert Lead in Sugar 6.0 For other views, you write the code for the view and put it in modules/modulename/views/view.viewname.php 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 14

15. MVC Framework – SugarView API 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 15

16. MVC Framework – SugarView API 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 16

17. MVC Framework – View Example 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 17 <?php class ViewExample extends SugarView { public function preDisplay() { if ( !is_admin($GLOBALS["current_user"]) ) sugar_die("Not an Admin"); } public function display() { echo "Hello Admin!"; } }

18. MVC Framework – ViewDetail Example 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 18 <?php require_once('include/MVC/View/views/view.detail.php'); class ContactsViewDetail extends ViewDetail { public function display() { $admin = new Administration(); $admin->retrieveSettings(); if(isset($admin->settings['portal_on']) && $admin->settings['portal_on']) { $this->ss->assign("PORTAL_ENABLED", true); } parent::display(); } }

19. 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 19 Where do I put my customizations? Controllers /custom/modules/Modulename/controller.php class CustomModulenameController extends SugarController Views /custom/modules/Modulename/views/view.viewname.php class CustomModulenameViewViewname extends ModulenameViewViewname If that class doesn’t exist extend from ViewViewname or SugarView

20. Metadata Layer 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 20

21. Kinds of metadata editviewdefs.php / detailviewdefs.php / quickcreatedefs.php Wireless variants: wireless.editviewdefs.php, wireless.detailviewdefs.php subpaneldefs.php listviewdefs.php wireless.listviewdefs.php searchdefs.php wireless.searchdefs.php SearchFields.php popupdefs.php 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 21

22. editviewdefs.php 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 22 <?php $viewdefs[$module_name]['EditView'] = array( 'templateMeta' => array( 'maxColumns' => '2', 'widths' => array( array('label' => '10', 'field' => '30'), array('label' => '10', 'field' => '30'), ), ), 'panels' =>array ( 'default' => array ( array ( 'name', 'assigned_user_name', ), array(array( 'name' => 'date_modified', 'customCode' => '{$fields.date_modified.value} {$APP.LBL_BY} {$fields.modified_by_name.value}', 'label' => 'LBL_DATE_MODIFIED', )), ), array( array ( 'description', ), ), ), );

23. subpaneldefs.php 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 23 <?php $layout_defs[$module_name] = array( 'subpanel_setup' => array( 'contacts' => array( 'order' => 20, 'module' => 'Contacts', 'sort_by' => 'last_name, first_name', 'sort_order' => 'asc', 'subpanel_name' => 'default', 'get_subpanel_data' => 'contacts', 'title_key' => 'LBL_CONTACTS_SUBPANEL_TITLE', 'top_buttons' => array( array('widget_class' => 'SubPanelTopButtonQuickCreate'), array( 'widget_class'=>'SubPanelTopSelectButton', 'mode'=>'MultiSelect’ ), ), ), ), );

24. searchdefs.php 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 24 <?php $searchdefs[$module_name] = array( 'templateMeta' => array( 'maxColumns' => '3', 'widths' => array('label' => '10', 'field' => '30'), ), 'layout' => array( 'basic_search' => array( 'name', array('name'=>'current_user_only', 'label'=>'LBL_CURRENT_USER_FILTER', 'type'=>'bool'), ), 'advanced_search' => array( 'name', array('name' => 'phone', 'label' =>'LBL_ANY_PHONE', 'type' => 'name'), array('name' => 'address_city', 'label' =>'LBL_CITY', 'type' => 'name'), array('name' => 'email', 'label' =>'LBL_ANY_EMAIL', 'type' => 'name'), array('name' => 'assigned_user_id', 'type' => 'enum', 'label' => 'LBL_ASSIGNED_TO', 'function' => array('name' => 'get_user_array', 'params' => array(false))), ), ), );

25. SearchFields.php 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 25 <?php $searchFields[$module_name] = array ( 'name' => array( 'query_type'=>'default'), 'current_user_only'=> array('query_type'=>'default', 'db_field'=>array('assigned_user_id'),'my_items'=>true, 'vname' => 'LBL_CURRENT_USER_FILTER', 'type' => 'bool'), 'assigned_user_id'=> array('query_type'=>'default'), );

26. popupdefs.php 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 26 <?php global $mod_strings; $popupMeta = array( 'moduleMain' => 'Account', 'varName' => 'ACCOUNT', 'orderBy' => 'name', 'whereClauses' => array( 'name' => 'accounts.name', 'billing_address_city' => 'accounts.billing_address_city', 'phone_office' => 'accounts.phone_office'), 'searchInputs' => array('name', 'billing_address_city', 'phone_office'), 'create' => array( 'formBase' => 'AccountFormBase.php', 'formBaseClass' => 'AccountFormBase', 'getFormBodyParams' => array('','','AccountSave'), 'createButton' => $mod_strings['LNK_NEW_ACCOUNT’]), 'listviewdefs' => array( 'NAME' => array( 'width' => '40', 'label' => 'LBL_LIST_ACCOUNT_NAME', 'link' => true,'default' => true,), ), 'searchdefs' => array( 'name', array('name' => 'assigned_user_id', 'label'=>'LBL_ASSIGNED_TO', 'type' => 'enum', 'function' => array('name' => 'get_user_array', 'params' => array(false))), ),);

27. Where do I put my customizations? Subpaneldefs custom/Extension/modules/Modulename/Ext/Layoutdefs/NameWhateverYouWant.php Need to run ‘Quick Repair and Rebuild’ after changes are made Everything else /custom/modules/Modulename/metadata Watch for Studio blowing out your changes. 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 27

28. Logic Hooks 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 28

29. Logic Hook Types 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 29

30. Logic Hook Types (cont) 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 30

31. Logic Hook Types (new in 6.0) 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 31

32. logic_hooks.php 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 32 <?php $hook_version = 1; $hook_array = Array(); $hook_array['before_save'] = Array(); $hook_array['before_save'][] = Array(1, 'AccountHooks', 'custom/Accounts/AccountHooks.php','AccountHooks', 'getParentAccountIndustry'); Parameters for Logic Hook Definition Parameter 1 - Sorting index used to sort the arrays of logic hook definitions before they are processed.Parameter 2 - A string value to identify the hookParameter 3 - Path to the PHP file to include which contains your logic hook codeParameter 4 - Name of the PHP class the logic hook method is inParameter 5 - Name of the PHP method to call

33. AccountHooks.php 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 33 <?php class AccountHooks { public function getParentAccountIndustry( SugarBean $bean, $event, $arguments ) { if ( empty($bean->industry) && !empty($bean->parent_id) ) { $parentAccountFocus = new Account(); $parentAccountFocus->retrieve($bean->parent_id); if ( !empty($parentAccountFocus->id) ) $bean->industry = $parentAccountFocus->industry; } } }

34. Where do I put my customizations? Application Level Logic Hooks /custom/modules/ Module Level Logic Hooks /custom/modules/Modulename/ 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 34

35. Themes 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 35

36. Theme Directory Layout css/ - contains all css files images/ - contains all images js/ - contains any js files. tpls/ - smarty templates themedef.php definition file. 12/30/08 ©2009 SugarCRM Inc. All rights reserved. 36

37. Themes can inherit from other themes Theme Inheritance Model 12/30/08 ©2009 SugarCRM Inc. All rights reserved. 37

38. Allow upgrade-safe modifications to themes All themes can be modified by putting the replacement or overriding file in the custom/theme/<themename> directory Image, HTML template file overrides are used as a replacement of the previous file Example: an image custom/theme/<themename>/dog.gif would be used instead of theme/<themename>/dog.gif CSS and Javascript files are combined in order of inheritance Uses cssmin and jsmin to help reduce file size No further code changes are required – changes are picked up automatically when themes cache is rebuilt. 12/30/08 ©2009 SugarCRM Inc. All rights reserved. 38

39. Resources 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 39 http://developers.sugarcrm.com Buy my book!

40. Thanks for coming! 4/14/10 ©2010 SugarCRM Inc. All rights reserved. 40