Sugar Community Edition 6.1 Documentation

Sugar Developer Guide

Table of Contents Previous Next

Version 6.1.0

Chapter 4 Customizing Sugar
Chapter 4 Customizing Sugar
You can customize Sugar to tailor the application to meet your business needs. This chapter explains the different ways to customize SugarCRM.
Introduction
The extension framework in Sugar was created to help implement the customization of existing modules or create entirely new modules. Through the various extensions available you can extend most of the functionality of Sugar in an upgrade-safe manner. The Module Builder and Studio tools, available from the Admin Home page, allow you to make the most common customizations that are outlined below. You can then further extend your system by adding upgrade-safe custom code.
Most common customizations are done with the suite of developer tools provided in the Sugar Admin screen. Those tools include:
•
Studio - Edit Dropdowns, Custom Fields, Layouts and Labels
•
Module Builder - Build new modules to expand the functionality of SugarCRM
•
Module Loader - Add or remove Sugar modules, themes, and language packs
•
Dropdown Editor - Add, delete, or change the dropdown lists in the application
•
Rename Tabs - Change the label of the module tabs
•
Configure Module Tabs and Subpanels - Choose which module tabs and sub-panels to display within the application
•
Configure Shortcut Bar – Select which modules are available in the Shortcuts bar.
•
Configure Grouped Modules - Create and edit groupings of tabs
For further information on how to use these tools, please refer to the Sugar Application Guide. This guide will go into more detail on how to use the Module Builder and the Module Loader, as well as how to extend the Sugar system at the code-level beyond what these tools provide.
Tips
Making upgrade-safe customizations
Because Sugar is an open source application, you have access to the source code. Keep in mind that any code customizations you make to the core files that ship with the Sugar application will need to be merged forward or re-factored manually when you upgrade to the next patch or major release.
However, any changes you make using the developer tools provided on the Admin screen (Module Builder, Studio, etc.) are upgrade-safe. Also, any code changes you make in the custom/ directory are also upgrade-safe.
Installing Third-Party Modules
Be aware that not all third-party modules you install on your Sugar system (such as modules found on SugarForge.org) have been designed to interoperate error-free with other modules and, hence, may not be upgrade-safe. Code changes made by a third-party developer and distributed in a module could potentially modify core files which would require special attention during an upgrade. Also, two different modules could conflict with one another in the changes they make to your system.
Naming Your Custom Modules
If you create a new module or a Sugar Dashlet without using the Module Builder, be sure to give your new directories unique names. This will prevent conflicts with future modules added by the Sugar team. For example, a best practice would be to add a unique prefix to your new module’s directory name such as “zz_Brokers” for a new Brokers module.
Be Familiar with Object Oriented Programming
Much of extending the Sugar functionality is based around extending and overriding the SugarCRM base classes. Developers need to be familiar with the basics of object-oriented programming and are encouraged to extend the SugarCRM base classes only to the minimum extent necessary.
Use Developer Mode when Customizing the User Interface
When developing in Sugar, we suggest that you turn on the Developer Mode (Admin->System Settings->Advanced->Developer Mode) to get the system to ignore the cached metadata files. This is especially helpful when you are directly altering templates, metadata, or language files. When using Module Builder or Studio, the system will automatically refresh the file cache. Be sure to turn off Developer Mode when you have completed your customizations since this mode does degrade system performance.
The Custom Directory
The Sugar system contains a top level directory called “custom” directory. This directory contains metadata files and custom code that override and extend the base Sugar functionality. Some of the files in this directory are auto-generated by the Module Builder, Studio, and Workflow tools (Sugar Professional and Sugar Enterprise only) and other files can be added or modified directly by a developer. Before discussing how a developer can use Sugar tools to modify the application, an understanding of the custom directory is useful.
Vardefs
Vardefs define field attributes for a given module. Existing vardefs can be modified and new vardefs can be created by modifying vardefs files in the custom directory.
Master Directories
Files in these directories can be edited and new files can be added to these directories.
/custom/Extension/modules/<MODULE_NAME>/Ext/Vardefs/
Production Directories
Files in these directories are auto-generated by the system and should not be modified.
/custom/modules/<MODULE_NAME>/Ext/Vardefs/vardefs.ext.php
Description
Vardefs files either replace field definitions entirely, or add to the ones that are available to a module. In the Master Directories you can have many files such as:
•
/custom/Extension/modules/Calls/Ext/Vardefs/New_vardefs.php
•
/custom/Extension/modules/Calls/Ext/Vardefs/Updated_Vardefs.php
During the repair function (Admin->Repair->Quick Repair and Rebuild), all of these files will be merged together into the production directory and they become the file:
/custom/modules/Calls/Ext/Vardefs/vardefs.ext.php
For example, a vardefs extension file for the Calls module could contain the following:
/custom/Extension/modules/Calls/ext/Vardefs/Import_Vardefs.php
<?php
$dictionary['Call']['fields']['parent_type']['vname'] = 'LBL_PARENT_TYPE';
$dictionary['Call']['fields']['parent_id']['vname'] = 'LBL_PARENT_ID';
$dictionary['Call']['fields']['deleted']['importable'] = false;
$dictionary['Call']['fields']['related_id'] = array (
'name' => 'related_id',
'vname' => 'LBL_RELATED_ID',
'type' => 'id',
'required' => false,
'reportable' => false,
'audited' => true,
'comment' => 'ID of a related record of this call',
);
?>
This would change the values for the “vname” of parent_type and parent_id, it would add an “importable” value to the deleted field and set it to false and then add a whole new field called related_id to the calls field list.
Languages
It is possible to override display string values for a given language and create entirely new strings used by new custom fields.
Master Directories
Files in these directories can be edited and new files can be added to these directories.
•
/custom/include/language/ (for $app_strings or $app_list_strings)
•
/custom/Extension/application/Ext/Include/
•
/custom/Extension/modules/<MODULE_NAME>/Ext/Language/ (for $mod_strings only)
Production Directories
Files in these directories are auto-generated by the system and should not be modified.
•
/custom/include/language/<LANGUAGE_TAG>.lang.ext.php
•
/custom/modules/<MODULE_NAME>/Ext/Languages/<LANGUAGE_TAG>.lang.ext.php
Description
Language files either replace entirely or add to the translated language items available to a module. In the Master Directories you can have many files like:
•
/custom/Extension/modules/Leads/Ext/Language/en_us.Custom_strings.php
•
/custom/Extension/modules/Leads/Ext/Language/en_us.Custom_Languages.php
During the repair function (Admin->Repair->Quick Repair and Rebuild), all of these files will be merged together into the production directory and they become the file:
/custom/modules/Leads/Ext/Language/en_us.lang.ext.php
For example, a language extension file for the Calls module could contain the following:
/custom/Extension/modules/Calls/ext/Languages/en_us.Import_Menu.php
<?php
// adding Import field changes
$mod_strings['LNK_IMPORT_CALLS'] = 'Import Calls';
$mod_strings['LBL_MODIFIED_NAME'] = 'Modified By';
$mod_strings['LBL_PARENT_TYPE'] = 'Parent Type';
$mod_strings['LBL_PARENT_ID'] = 'Parent ID';
?>
This would add four new display strings to the Calls module.
Shortcuts
It is possible to override or create new Shortcuts menu items.
Master Directories
Files in these directories can be edited and new files can be added to these directories.
•
/custom/Extension/application/Ext/Menus/
•
/custom/Extension/modules/<MODULE_NAME>/Ext/Menus/
Production Directories
Files in these directories are auto-generated by the system and must not be modified.
•
/custom/application/Ext/Menus/menu.ext.php
•
/custom/modules/<MODULE_NAME>/Ext/Menus/menu.ext.php
Description
Shortcut menu files either replace entirely, or add to the menu items available under the “Actions” list on the module tabs. In the Master Directories you can have many files like:
•
/custom/Extension/modules/Calls/Ext/Menus/New_menu_items.php
•
/custom/Extension/modules/Calls/Ext/Menus/Custom_Menus.php
•
/custom/Extension/modules/Calls/Ext/Menus/Menu_items.php
During the repair function (Admin->Repair->Quick Repair and Rebuild), all of these files will be merged together into the production directory and they become the file:
/custom/modules/Leads/ext/Menus/menu.ext.php
For example, a menu extension file for the Calls module could contain the following:
<?php
if(ACLController::checkAccess('Calls', 'import', true)) {
$module_menu[]=Array("index.php?module=Calls&action=MakeIndex",
translate('LNK_INDEX_CALLS'), "Import"
);
}
?>
 
This would add a menu item to the Calls module’s Shortcuts menu. The $module_menu array takes three elements.
•
The first is the URL that the menu item will run.
•
The second is the text that will be shown on the menu, in this case we added some custom language text in a separate custom language file that we will go over later in this document.
•
The last is the name of the icon associated with this menu option. This word will have “.gif” added to the end of it. If you want to use a png file here you must rename import.png to import.gif and load it into the themes/default/images directory. Even though it is named with the 'gif' extension it will still work.
If you added a $module_menu=array(); to the top of this file, you would effectively clear out any of the standard menu items. You could then replace them all with new definitions.
If the custom file is in the /custom/Extension/application/Ext/Menus/ directory, then your menu changes will affect shortcut menus in every module.
Layoutdefs
Master Directories
Files in these directories can be edited and new files can be added to these directories.
•
/custom/Extension/application/Ext/Layoutdefs/
•
/custom/Extension/modules/<MODULE_NAME>/Ext/Layoutdefs/
Production Directories
Files in these directories are auto-generated by the system and must not be modified.
•
/custom/application/Ext/Layoutdefs/layoutdefs.ext.php
•
/custom/modules/<MODULE_NAME>/Ext/Layoutdefs/layoutdefs.ext.php
Rule
Use the following rule to add a sub-panel to a module:
For{$modulename}.php
where modulename is the name of the module to which you are adding the sub-panel.
Description
Layoutdefs are a little more complex than the other customization types. Each customization is made across two files, the layout definition file and the actual layout file. In the Master Directories you can have many files like the following:
•
/custom/Extension/modules/Accounts/Ext/Layoutdefs/_overrideAccountContactsForAccounts.php
•
/custom/Extension/modules/Accounts/Ext/Layoutdefs/_overrideAccountOpportunitiesForAccounts.php
During the repair function (Admin->Repair->Quick Repair and Rebuild), all of these files are merged together into the production directory to become the file:
/custom/modules/Accounts/Ext/Layoutdefs/layoutdefs.ext.php
For example, a layoutdefs extension file for the Accounts module could contain the following:
/custom/Extension/modules/Accounts/ext/Layoutdefs/_overrideAccountContactsForAccounts.php
<?php
$layout_defs["Accounts"]["subpanel_setup"]["accounts_documents"] = array (
'order' => 100,
'module' => 'Documents',
'subpanel_name' => 'default',
'sort_order' => 'asc',
'sort_by' => 'id',
'title_key' => 'LBL_ACCOUNTS_DOCUMENTS_FROM_DOCUMENTS_TITLE',
'get_subpanel_data' => 'accounts_documents',
);
 
$layout_defs['Accounts']['subpanel_setup']['contacts']['override_subpanel_name'] = 'AccountForAccounts';
?>
 
The first array is setting up a subpanel for a new relationship between Documents and Accounts. While there are many other files required to completely define this module relationship, (which we will go over in the Relationship section below), this file just creates the links to the new subpanel that would be located at:
custom/modules/Documents/Ext/subpanels/default.php
The second array simply points the system at a new subpanel definition file that will replace the subpanel that shows Contacts related to Accounts. Since you cannot merge subpanel definition files, they do not exist in the custom/Extension/ directory. The array in this file would tell the system to load the file:
custom/modules/Contacts/metadata/subpanels/AccountForAccounts.php
Module Builder
The Module Builder functionality allows programmers to create custom modules without writing code, and to create relationships between new and existing CRM modules. To illustrate how to use Module Builder, this article will show how to create and deploy a custom module. In this example, a custom module to track media inquiries will be created to track public relations requests within a CRM system. This use case is an often requested enhancement for CRM systems that applies across industries.
Creating New Modules
Module Builder functionality is managed within the ‘Developer Tools’ section of Sugar’s administration console.
Upon selecting ‘Module Builder’, the user has the option of creating a “New Package”. Packages are a collection of custom modules, objects, and fields that can be published within the application instance or shared across instances of Sugar. Once the user selects “New Package”, the user names and describes the type of Custom Module to be created. A package key, usually based on the organization or name of the package creator is required to prevent conflicts between two packages with the same name from different authors. In this case, the package will be named “MediaTracking” to explain its purpose, and a key based on the author name will be used.
Once the new package is created and saved, the user is presented with a screen to create a Custom Module. Upon selecting the “New Module” icon, a screen appears showing six different object templates.
Understanding Object Templates
Five of the six object templates contain pre-built CRM functionality for key CRM use cases. These objects are:”basic”, “company”, “file”, “issue”, “person”, and “sale”. The “basic” template provides fields such as Name, Assigned to, Team, Date Created, and Description. As their title denotes, the rest of these templates contain fields and application logic to describe entities similar to “Accounts”, “Documents, “Cases”, “Contacts”, and “Opportunities”, respectively. Thus, to create a Custom Module to track a type of account, you would select the “Company” template. Similarly, to track human interactions, you would select “People”.
For the media tracking use case, the user will use the object template “Issue” because inbound media requests have similarities to incoming support cases. In both examples, there is an inquiry, a recipient of the issue, assignment of the issue and resolution. The final object template is named “Basic” which is the default base object type. This allows the administrator to create their own custom fields to define the object.
Upon naming and selecting the Custom Module template named “Issue”, the user can further customize the module by changing the fields and layout of the application, and creating relationships between this new module and existing standard or custom modules. This Edit functionality allows user to construct a module that meets the specific data requirements of the Custom Module.
Editing Module Fields
Fields can be edited and created using the field editor. Fields inherited from the custom module's templates can be relabeled while new fields are fully editable. New fields are added using the “Add Field” button. This will bring up a tab where you can select the type of field to add as well as any properties that field type requires.
Editing Module Layouts
The layout editor can be used to change the appearance of the screens within the new module, including the EditView, DetailView and ListView screens. When editing the Edit View or the Detail View, new panels and rows can be dragged from the toolbox on the left side to the layout area on the right. Fields can then be dragged between the layout area and the toolbox. Fields are removed from the layout by dragging them from the layout area to the recycling icon. Fields can be expanded or collapsed to take up one or two columns on the layout using the plus and minus icons. List, Search, Dashlet, and Subpanel views can be edited by dragging fields between hidden/visible/available columns.
Building Relationships
Once the fields and layout of the Custom Module have been defined, the user then defines relationships between this new module and existing CRM data by clicking “View Relationships”. The “Add Relationship” button allows the user to associate the new module to an existing or new custom module in the same package. In the case of the Media Tracker, the user can associate the Custom Module with the existing, standard ‘Contacts’ module that is available in every Sugar installation using a many-to-many relationship. By creating this relationship, end-users will see the Contacts associated with each Media Inquiry. We will also add a relationship to the activities module so that a Media Inquiry can be related to calls, meetings, tasks, and emails.
Publishing and Uploading Packages
After the user has created the appropriate fields, layouts, and relationships for the custom modules, this new CRM functionality can be deployed. Click the “Deploy” button to deploy the package to the current instance. This is the recommended way to test your package while developing. If you wish to make further changes to your package or custom modules, you should make those changes in Module Builder, and click the Deploy button again. Clicking the Publish button generates a zip file with the Custom Module definitions. This is the mechanism for moving the package to a test environment and then ultimately to the production environment. The Export button will produce a module loadable zip file, similar to the Publish functionality, except that when the zip file is installed, it will load the custom package into Module Builder for further editing. This is a good method for storing the custom package in case you would like to make changes to it in the future on another Sugar instance.
After the new package has been published, the administrator must commit the package to the Sugar system through the Module Loader. The administrator uploads the files and commits the new functionality to the live application instance.
Adding Custom Logic using Code
While the key benefit of the Module Builder is that the Administrator user is able to create entirely new modules without the need to write code, there are still some tasks that require writing PHP code. For instance, adding custom logic or making a call to an external system through a Web Service. This can be done in one of two methods.
Logic Hooks
One way is by writing PHP code that leverages the event handlers, or “logic hooks”, available in Sugar. In order to accomplish this, the developer must create the custom code and then add it to the manifest file for the “Media Inquiry” package.
Here is some sample code for a simple example of using the logic hooks. This example adds a time stamp to the description field of the Media Inquiry every time the record is saved.
First, create the file AddTimeStamp.php with the following contents.
<?php
//prevents directly accessing this file from a web browser
if(!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');
 
class AddTimeStamp {
function StampIt(& $focus, $event){
global $current_user;
$focus->description .= “\nSaved on ”. date(“Y-m-d g:i a”). “ by ”. $current_user->user_name;
}
}
?>
 
Next register this custom function by creating the file logic_hooks.php with the following contents.
<?php
// Do not store anything in this file that is not part of the array or the hook version. This file will
// be automatically rebuilt in the future.
$hook_version = 1;
$hook_array = Array();
// position, file, function
$hook_array['before_save'] = Array();
$hook_array['before_save'][] = Array(1, 'custom', 'custom/modules/Media/AddTimeStamp.php ','AddTimeStamp', 'StampIt');
?>
 
Now add these two files to the Media Inquiries zip file you just saved. Create a directory called “SugarModules/custom/” in the zip file and add the two files there. Then modify the manifest.php in the zip file to include the following definition in the $install_defs[‘copy’] array.
array (
'from' => '<basepath>/SugarModules/custom',
'to' => 'custom/modules/jsche_Media',
),
Custom Bean files
Another method is to add code directly to the custom bean. This is a more complicated approach because it requires understanding the SugarBean class. However it is a far more flexible and powerful approach.
First you must “build” your module. This can be done by either deploying your module or clicking the Publish button. Module Builder will then generate a folder for your package in “custom/modulebuilder/builds/”. Inside that folder is where Sugar will have placed the bean files for your new module(s). In this case we want
“custom/modulebuilder/builds/MediaTracking/SugarModules/modules/jsche_mediarequest”
Inside you will find two files of interest. The first one is {module_name}sugar.php. This file is generated by Module Builder and may be erased by further changes in module builder or upgrades to the Sugar application. You should not make any changes to this file. The second is {module_name}.php. This is the file where you make any changes you would like to the logic of your module. To add our timestamp, we would add the following code to jsche_mediarequest.php
function save($check_notify = FALSE) {
global $current_user;
$this->description .= "\nSaved on " . date("Y-m-d g:i a"). " by "
. $current_user->user_name;
parent::save($check_notify);
}
The call to the parent::save function is critical as this will call on the out of box SugarBean to handle the regular Save functionality. To finish, re-deploy or re-publish your package from Module Builder.
You can now upload this module, extended with custom code logic, into your Sugar application using the Module Loader as described earlier.
Using the New Module
After you upload the new module, the new custom module appears in the Sugar instance. In this example, the new module, named “Media” uses the object template “Issue” to track incoming media inquiries. This new module is associated with the standard “Contacts” modules to show which journalist has expressed interest. In this example, the journalist has requested a product briefing. On one page, users can see the nature of the inquiry, the journalist who requested the briefing, who the inquiry was assigned to, the status, and the description.
Module Loader
The Module Loader not only installs custom modules but installs the latest patches, themes, language packs, and Sugar Dashlets. The $upgrade_manifest variable is used to upgrade the application.
The Module Loader relies on a file named manifest.php, which resides in the root directory of any installable package.
Manifest Overview
The following section outlines the parameters specified in the $manifest array contained in the manifest file (manifest.php). An example manifest file is included later for your reference.
$manifest array elements provide the Module Loader with descriptive information about the extension.
o
acceptable_sugar_flavors - Specifies which Sugar Editions the package can be installed on. Accepted values are any combination of: OS (valid prior to Sugar 5.0.0), CE (valid after Sugar 5.0.0), PRO, and ENT.
o
acceptable_sugar_versions - This directive contains two arrays:
o
exact_matches: each element in this array should be one exact version string, i.e. “6.0.0b” or “6.1.0”
o
regex_matches: each element in this array should be one regular expression designed to match a group of versions, i.e. “6\\.1\\.0[a-z]”
o
author - Contains the author of the package, i.e. “SugarCRM Inc.”
o
copy_files - An array detailing the source and destination of files that should be copied during installation of the package. See the example manifest file below for details.
o
dependencies - A set of dependencies that must be satisfied to install the module. This contains two arrays:
o
id_name : the unique name found in $installdefs.
o
version: the version number.
o
description - A description of the package. Displayed during installation.

Note: Apostrophes (') are not supported in your description and will cause a Module Loader error.
o
icon - A path (within the package ZIP file) to an icon image that will be displayed during installation. Examples include: “./patch_directory/icon.gif” and “./patch_directory/images/theme.gif”
o
is_uninstallable - Setting this directive to TRUE allows the Sugar administrator to uninstall the package. Setting this directive to FALSE disables the uninstall feature.
o
name - The name of the package. Displayed during installation. Note: Apostrophes (') are not supported in your description and will cause a Module Loader error.
o
published_date - The date the package was published. Displayed during installation.
o
type - The package type. Accepted values are:
o
langpack - Packages of type langpack will be automatically added to the “Language” dropdown on the Sugar Login screen. They are installed using the Upgrade Wizard.
o
module - Packages of type module are installed using the Module Loader.
o
patch - Packages of type patch are installed using the Upgrade Wizard.
o
theme - Packages of type theme will be automatically added to the “Theme” dropdown on the Sugar Login screen. They are installed using the Upgrade Wizard.
o
version - The version of the patch, i.e. “1.0” or “0.96-pre1” .
Installdef Definition
The following section outlines the parameters specified in the $installdef array contained in the manifest file (manifest.php). An example manifest file is included later for your reference.
$installdef array elements are used by the Module Loader to determine the actual installation steps that need to be taken to install the extension.
•
id - A unique name for your module; for example, “Songs”
•
copy - An array detailing files to be copied to the Sugar directory. A source path and destination path must be specified for each file or directory. See the example manifest file below for details.
•
language - An array detailing individual language files for your module. The source path, destination file, and language pack name must be specified for each language file. See the example manifest file below for details.
•
layoutdefs - An array detailing individual layoutdef files, which are used primarily for setting up subpanels in other modules. The source path and destination module must be specified for each layoutdef file. See the example manifest file below for details.
•
layoutfields - An array detailing custom fields to be added to existing layouts. The fields will be added to the edit and detail views of target modules. See the example manifest file below for details.
•
vardefs - An array detailing individual vardef files, which are used primarily for defining fields and non many-to-many relationships in other modules. The source path and destination module must be specified for each vardef file. See the example manifest file below for details.
•
menu - An array detailing the menu file for your new module. A source path and destination module must be specified for each menu file. See the example manifest file below for details.
•
beans - An array specifying the bean files for your new module. The following sub-directives must be specified for each bean:
o
module: Your module’s name, “Songs”
o
class: Your module’s primary class name, “Song”
o
path: The path to your bean file where the above class is defined.
o
tab: Controls whether or not your new module appears as a tab.
•
relationships - An array detailing relationship files, used to link your new modules to existing modules. A metadata path must be specified for each relationship. See the example manifest file below for details.
•
custom_fields - An array detailing custom fields to be installed for your new module. The following sub-directives must be specified for each custom field:
name: The internal name of your custom field. Note that your custom field will be referred to as <name>_c, as “_c” indicates a custom field.
label: The visible label of your custom field
type: The type of custom field. Accepted values include text, textarea, double, float, int, date, bool, enum, and relate.
max_size: The custom field’s maximum character storage size
require_option: Used to mark custom fields are either required or option. Accepted values include optional and required.
default_value: Used to specify a default value for your custom field
ext1: Used to specify a dropdown name (only applicable to enum type custom fields)
ext2: Unused
ext3: Unused
audited: Used to denote whether or not the custom field should be audited. Accepted values include 0 and 1.
module: Used to specify the module where the custom field will be added.
Upgrade Definition
This array definition describes the release(s) leading to the "version" element defined in $manifest. In the sample manifest below it defines the Songs module versions 1.0 and 1.5 as preceding the current version 2.0.
Module Loader Restrictions
SugarCRM’s hosting objective is to maintain the integrity of the standard Sugar functionality when we upgrade a customer instance, and limit any negative impact our upgrade has on the customer’s modifications.
Access Controls
The Module Loader includes a Module Scanner, which grants system administrators the control they need to determine the precise set of actions that they are willing to offer in their hosting environment. This feature is available in all editions of Sugar. Anyone who is hosting Sugar products can advantage of this feature as well.
The specific Module Loader restrictions for the Sugar Open Cloud are documented in the Sugar Knowledge Base.
Enable Package Scan
Scanning is disabled in default installations of Sugar, and can be enabled through a configuration setting. This setting is added to config.php or config_override.php, and is not available to Administrator users to modify through the Sugar interface.
To enable Package Scan and its associated scans, add this setting to config.php or config_override.php:
$GLOBALS[‘sugar_config’][‘moduleInstaller’][‘packageScan’] = true;

There are two categories of access controls now available:
1.
File scanning
2.
Module Loader actions
Enable File Scan
By enabling Package Scan, File Scan will be performed on all files in the package uploaded through Module Loader. File Scan will be performed when a Sugar administrator attempts to install the package.
File Scan performs two types of checks:
1.
File extension must be in the approved list of valid extension types
a.
The default list of valid extension types is detailed in Appendix A.
b.
Files do not contain function calls that are considered suspicious, based on a blacklist.
i.
Backticks (`) are never allowed by File Scan.
ii.
The default blacklist of functions is detailed in Appendix B.
To disable File Scan, add the following configuration setting to config.php or config_override.php:
$GLOBALS[‘sugar_config’][‘moduleInstaller’][‘disableFileScan’] = true;

To add more file extensions to the approved list of valid extension types, add the file extensions to the validExt array. The example below adds a .log file extension and .htaccess to the valid extension type list:
$GLOBALS[‘sugar_config’][‘moduleInstaller’][‘validExt’] = array(‘log’, ‘htaccess’);

To add additional function calls to the black list, add the function calls to the blackList array. The example below blocks the strlen() and strtolower() functions from being included in the package:
$GLOBALS[‘sugar_config’][‘moduleInstaller’][‘blackList’] = array(‘strlen’, ‘strtolower’);
To override the black list and allow a specific function to be included in packages, add the function call to the blackListExempt array. The example below removes the restriction for the file_put_contents() function, allowing it to be included in the package:
$GLOBALS[‘sugar_config’][‘moduleInstaller’][blackListExempt’] = array(‘file_put_contents’);
Disable Module Loader Actions
Certain Module Loader actions may be considered less desirable than others by a System Administrator. A System Administrator may want to allow some Module Loader actions, but disable specific actions that could impact the upgrade-safe integrity of the Sugar instance.
By default, all Module Loader actions are allowed. Enabling Package Scan does not affect the Module Loader actions.
To disable specific Module Loader actions, add the action to the disableActions array. The example below restricts the pre_execute and post_execute actions:
$GLOBALS[‘sugar_config’][‘moduleInstaller’][‘disableActions’] = array(‘pre_execute’, ‘post_execute’);

A list of all actions available in Module Loader is detailed in Appendix C.
$GLOBALS['sugar_config']['disable_uw_upload'] = true;

This configuration parameter blocks the upload capabilities of the Upgrade Wizard, intended for hosting providers. It behaves similarly to the use_common_ml_dir parameter for Module Loader.
Restricted Copy
To ensure upgrade-safe customizations, it is necessary for system administrators to restrict the copy action to prevent modifying the existing Sugar source code files. New files may be added anywhere (to allow new modules to be added), but any core Sugar source code file must not be overwritten. This is enabled by default when you enable Package Scan.
To disable Restricted Copy, use this configuration setting:
$GLOBALS[‘sugar_config’][‘moduleInstaller’][‘disableRestrictedCopy’] = true;
 
Default Valid File Extensions
•
png
•
gif
•
jpg
•
css
•
js
•
php
•
txt
•
html
•
htm
•
tpl
•
md5
•
pdf
Default Blacklist of Functions
eval
exec
system
shell_exec
passthru
chgrp
chmod
chown
file_put_contents
file
fileatime
filectime
filegroup
fileinode
filemtime
fileowner
fileperms
fopen
is_executable
is_writable
is_writable
lchgrp
lchown
linkinfo
lstat
mkdir
parse_ini_file
rmdir
stat
tempnam
touch
ulink
getimagesize
copy
link
rename
symlink
move_uploaded_file
chdir
chroot
sugar_chown
sugar_fopen
sugar_mkdir
sugar_file_put_contents
sugar_chgrp
sugar_chmod
sugar_touch
Module Loader Actions
pre_execute – Called before a package is installed
install_mkdirs – Creates directories
install_copy – Copies files or directories
install_images – Install images into the custom directory
install_menus – Installs menus to a specific page or the entire Sugar application
install_userpage – Adds a section to the User page
install_dashlets – Installs dashlets into the Sugar application
install_administration – Installs an administration section into the Admin page
install_connectors – Installs Sugar Cloud Connectors
install_vardefs – Modifies existing vardefs
install_layoutdefs – Modifies existing layouts
install_layoutfields – Adds custom fields
install_relationships – Adds relationships
install_languages – Installs language files
install_logichooks – Installs a new logic hook
post_execute – Called after a package is installed

Sample Manifest
The following sample manifest file defines the $manifest and $installdef array elements for a new module (Songs) which depends on two other modules: "Whale Pod" and "Maps". In addition to defining the $manifest and $installdef array elements, it also defines the $upgrade_manifest array.
<?php
$manifest = array(
'acceptable_sugar_versions' => array(),
'is_uninstallable' => true,
'name' => 'Song Module',
'description' => 'A Module for all your song needs',
'author' => 'Ajay',
'published_date' => '2005/08/11',
'version' => '2.0',
'type' => 'module',
'icon' => '',
'dependencies' => array (
array ('id_name' => 'whale_pod', 'version => '1.0'),
array ('id_name' => 'maps', 'version => '1.5'),
),
);
$installdefs = array (
'id' => 'songs',
'image_dir' => '<basepath>/images',
'copy' => array (
array (
'from' => '<basepath>/module/Songs',
'to' => 'modules/Songs',
),
),
'language' => array (
'from'=> '<basepath>/administration/en_us.songsadmin.php'
'to_module'=> 'application',
'language'=>'en_us'
),
array (
'from'=> '<basepath>/administration/en_us.songsadmin.php',
'to_module'=> 'Administration',
'language'=>'en_us'
),
),
'layoutdefs'=> array(
array(
'from'=> '<basepath>/layoutdefs/contacts_layout_defs.php',
'to_module'=> 'Contacts',
),
),
'layoutfields'=> array(
array(
'additional_fields'=> array(
'Songs' => 'music_name_c',
),
),
array(
'additional_fields'=> array(
'Songs' => 'label_company_c',
),
),
 
),
'vardefs'=> array(
array(
'from'=> '<basepath>/vardefs/contacts_vardefs.php',
'to_module'=> 'Contacts',
),
),
'administration'=> array (
array ( 'from'=>'<basepath>/administration/songsadminoption.php', ),
),
'beans'=> array (
array (
'module'=> 'Songs',
'class'=> 'Song',
'path'=> 'modules/Songs/Song.php',
'tab'=> true,
)
),
'relationships'=>array (
array (
'meta_data'=>'<basepath>/relationships/contacts_songsMetaData.php',
),
array (
'meta_data'=>'<basepath>/relationships/products_songsMetaData.php',
)
),
'custom_fields'=>array (
'array (
'name'=> 'music_name',
'label'=>'Music Name',
'type'=>'varchar',
'max_size'=>255,
'require_option'=>'optional',
'default_value'=>' ',
'ext1' => 'name',
'ext2' => 'Accounts',
'ext3' => ' ',
'audited'=>0,
'module'=>'Songs',
),
array (
'name'=>'label_company',
'label'=>'Label',
'type'=>'relate',
'max_size'=>36,
'require_option'=>'optional',
'default_value'=>'',
'ext1'=>'name',
'ext2'=>'Accounts',
'ext3'=>'', 'audited'=>0,
'module'=>'Songs',
),
),
);
 
$upgrade_manifest = array (
'upgrade_paths' => array (
'1.0' => array(
'id'=>'songs',
'copy'=>array(
array (
'from'=> '<basepath>/module/Songs',
'to'=> 'modules/Songs',
),
),
),
'1.5' => array (
'id'=>'songs',
'copy' => array(
array (
'from'=> '<basepath>/module/Songs',
'to'=> 'modules/Songs',
),
),
),
),
);
?>
Business Logic Hooks
Custom Logic (or "Business Logic Hooks") allows you to add functionality to certain actions, such as before saving a bean, in an upgrade-safe manner. This is accomplished by defining hooks, which are placed in the custom/ directory, which will be called in the SugarBean in response to events at runtime. Because the code is located separate from the core SugarCRM code, it is upgrade-safe.
See this SugarForge project for a complete example of a useful business hook.
Hook Definition
The code that declares your custom logic is located in: custom/modules/<CURRENT_MODULE>/logic_hooks.php. The format of the declaration follows.
$hook_version
All logic hooks should define the $hook_version that should be used. Currently, the only supported $hook_version is 1.
$hook_version = 1
$hook_array
Your logic hook will also define the $hook_array. $hook_array is a two dimensional array:
o
name: the name of the event that you are hooking your custom logic to
o
array: an array containing the parameters needed to fire the hook
A best practice is for each entry in the top level array to be defined on a single line to make it easier to automatically replace this file. Also, logic_hooks.php should contain only hook definitions; because the actual logic is defined elsewhere.
For example:
$hook_array['before_save'][] = Array(1, test, 'custom/modules/Leads/test12.php', 'TestClass', 'lead_before_save_1');
Available Hooks
The hooks are processed in the order in which they are added to the array. The first dimension is simply the current action, for example before_save. The following hooks are available:
Application hooks
These hooks do not make use of the $bean argument.
o
after_ui_frame
o
Fired after the frame has been invoked and before the footer has been invoked
o
after_ui_footer
o
Fired after the footer has been invoked
o
server_round_trip
o
Fired at the end of every Sugar page
Module hooks
o
before_delete
o
Fired before a record is deleted
o
after_delete
o
Fired after a record is deleted
o
before_restore
o
Fired before a record is undeleted
o
after_restore
o
Fired after a record is undeleted
o
after_retrieve
o
Fired after a record has been retrieved from the database. This hook does not fire when you create a new record.
o
before_save
o
Fired before a record is saved.
Note: With certain modules, like Cases and Bugs, the human-readable ID of the record (like the case_number field in the Case module), is not available within a before_save call. This is because this business logic has not been executed yet.
o
after_save
o
Fired after a record is saved.
Note: With certain modules, like Cases and Bugs, the human-readable ID of the record (like the case_number field in the Case module), is not available within a before_save call. This is because this business logic simply has not been executed yet.
o
process_record
o
Fired immediately prior to the database query resulting in a record being made current. This gives developers an opportunity to examine and tailor the underlying queries. This is also a perfect place to set values in a record’s fields prior to display in the DetailView or ListView. This event is not fired in the EditView.
Hooks for Users module
o
before_logout
o
Fired before a user logs out of the system
o
after_logout
o
Fired after a user logs out of the system
o
after_login
o
Fired after a user logs into the system.
o
after_logout
o
Fired after a user logs out of the system.
o
before_logout
o
Fired before a user logs out of the system.
o
login_failed
o
Fired on a failed login attempt
Options Array
The second dimension is an array consisting of:
o
Processing index => For sorting before exporting the array
o
Label/type => Some string value to identify the hook
o
PHP file to include => Where your class is located. Insert into ./custom.
o
PHP class the method is in => The name of your class
o
PHP method to call => The name of your method
Thus a given class may have multiple methods to fire, each within a single upgrade-safe PHP file.
The method signature for version 1 hooks is:
function NAME(&$bean, $event, $arguments)
 
Where:
o
$bean - $this bean passed in by reference.
o
$event - The string for the current event (i.e. before_save)
o
$arguments - An array of arguments that are specific to the event.

Packaging Custom Logic Hooks
You can package logic hooks with a package and load through the Module Loader.
Along with the other directives for packaging files you can include an entry for ‘logic_hooks’. A snippet of the manifest.php may look similar to this:
<?php
$installdefs = array(
'logic_hooks' => array(
array(
'module' => 'Accounts',
'hook' => 'after_save',
'order' => 99,
'description' => 'Account sample logic hook',
'file' => 'modules/Sample/sample_account_logic_hook_file.php',
'class' => 'SampleLogicClass',
'function' => 'accountAfterSave',
),
),
);
You must include the ‘modules/Sample/sample_account_logic_hook_file.php’ as part of your install_defs ‘copy’ directive so it can be run from the logic hook. When the Module Loader encounters the ‘logic_hooks’ entry in the installdefs, it will write out the appropriate file so that your logic hooks can be executed.
Using Custom Logic Hooks
The section above shows how to create a custom_logic_hook that runs the function updateDescription() from the class updateDescription (those do not have to be the same as they are in this example) in the PHP file updateDescription.php. Below is the actual script from that PHP file.
class updateDescription {
function updateDescription(&$bean, $event, $arguments) {
$bean->description = html_entity_decode($bean->description);
$bean->fetched_row['description'] = $bean->description;
}
}
You see that the $bean is fed into the function and allows access to all of the fields for the currently selected record. Any changes you make to the array will be reflected in the actual data. For example, in this script we are changing the description field. As shown above, there is
$event is set to whatever event is currently running like after_retrieve or before_delete.
Tips
A few cautions around using logic hooks apply:
o
It is not possible to hook logic to beans being displayed in a sub-panel.
o
There is no bean that fires specifically for the ListView, DetailView or EditViews user interface events. Use either the 'process_record' or 'after_retrieve' logic hooks.
o
In order to compare new values with previous values to see whether a change has happened, use $bean->fetched_row['<field>'] (old value) and $bean-><field> (new value) in the before_save logic hook.
o
Make sure that the permissions on your logic_hooks.php file and the class file that it references are readable by the web server. If this is not done, Sugar will not read the files and your business logic extensions will not work.
For example, *nix developers who are extending the Tasks logic should use the following command for the logic_hooks file and the same command for the class file that will be called.
[sugarcrm]# chmod +r custom/modules/Tasks/logic_hooks.php
 
o
Make sure that the entire custom/ directory is writable by the web server, or else the logic hooks code will not work properly.
User Interface Customizations
While the intention of the metadata framework is to abstract some of the value retrieval and display logic for the modules, there will inevitably be a need to customize the framework with separate hooks and logic pertaining to the module's unique business needs.
Custom Grouping of Values
This is a common scenario in DetailViews, especially for address blocks. This can be achieved as follows:
array (
'name' => 'date_modified',
'customCode' => '{$fields.date_modified.value} {$APP.LBL_BY} {$fields.modified_by_name.value}',
'label' => 'LBL_DATE_MODIFIED',
),

This will group the date_modified value and the modified_by_name values together with the $APP.LBL_BY label in between. The 'customCode' key is a direct Smarty inline code replacement. At the time of parsing the $fields array will be populated with the values populated for the request bean instance.
Custom Buttons
By default, the metadata framework provides default implementations for Cancel, Delete, Duplicate, Edit, Find Duplicates, and Save buttons. However, you may wish to use some of the default buttons or add additional buttons. Here is an example:
'templateMeta' => array(
'form' => array(
'buttons'=>array('EDIT', 'DUPLICATE', 'DELETE', array(
'customCode'=>
'<form action="index.php" method="POST" name="Quote2Opp" id="form">
<input title="{$APP.LBL_QUOTE_TO_OPPORTUNITY_TITLE}"
accessKey="{$APP.LBL_QUOTE_TO_OPPORTUNITY_KEY}"
class="button"type="submit"
name="opp_to_quote_button"
value="{$APP.LBL_QUOTE_TO_OPPORTUNITY_LABEL}">
</form>'
),
),
),

Here we are adding a custom button with the label defined in the Smarty variable {$APP.LBL_QUOTE_TO_OPPORTUNITY_LABEL}. The EDIT, DUPLICATE and DELETE buttons are rendered and then the snippet of code in this 'customCode' block is added.
The code to render the buttons specified in the metadata files may be found in include/Smarty/function.sugar_button.php.
Creating New Custom Displays
In this scenario, you wish to take advantage of the metadata framework to do some of the processing for a subset of the fields. However, the provided user interface generated does not meet the needs of your module, which requires richer UI functionality. Typically this scenario occurs when the EditView or DetailView for the module contains UI components that do not fit the framework of a table layout that produced by the metadata. For example, in addition to displaying the properties for the bean instance of the module, there is also a lot of information to be displayed for related beans, mashups, etc.
This type of customization may be achieved by a combination of overriding the footer.tpl file in the templateMeta section of the metadata file and creating a view.edit.php file to override the default MVC EditView handling. For example, consider the Quotes module's editviewdefs.php file:
'templateMeta' => array(
'maxColumns' => '2',
'widths' => array(
array('label' => '10', 'field' => '30'),
array('label' => '10', 'field' => '30')
),
'form' => array('footerTpl'=>'modules/Quotes/tpls/EditViewFooter.tpl'),
),

Note: You do not have to necessarily create a view.edit.php file, but usually at this point of customization, you will want to add variables to your customized template that are not assigned by the generic EditView handling from the MVC framework. See the next example, Overriding the View, for more information about sub-classing the EditView and assigning Smarty variables to the resulting templates.
Your EditViewFooter.tpl file can now render the necessary user interface code that the generic metadata framework could not:
{$SOME_CRAZY_UI_WIDGET} <----- You can either create this HTML in edit.view.php or place it here
<applet codebase="something"> <---- Let's add an Applet!
</applet>
{{include file='include/EditView/footer.tpl'}} <--- Include the generic footer.tpl file at the end

If you want to edit the top panel to provide customized widgets then you can override the header.tpl file instead. In that scenario, the smarty tag to include the generic header.tpl would likely appear at the top of the custom template file.
Overriding the View
Using the MVC framework, you define your module's own view.edit.php or view.detail.php file to subclass ViewEdit (for EditView) or ViewDetail (for DetailView). Then you override either the process or display methods to do any intermediary processing as necessary. This technique should be employed when you still want to take advantage of the rendering/layout formatting done by the metadata framework, but wish to tweak how some of the values are retrieved.
// Contents of module/[$module]/view/view.edit.php file
require_once('include/json_config.php');
require_once('include/MVC/View/views/view.edit.php');
class CallsViewEdit extends ViewEdit {
function CallsViewEdit(){
parent::ViewEdit();
}
 
function display() {
global $json;
$json = getJSONobj();
$json_config = new json_config();
if (isset($this->bean->json_id) && !empty ($this->bean->json_id)) {
$JavaScript = $json_config->get_static_json_server(false, true, 'Calls', $this->bean->json_id);
} else {
$this->bean->json_id = $this->bean->id;
$JavaScript = $json_config->get_static_json_server(false, true, 'Calls', $this->bean->id);
}
 
// Assign the Javascript code to Smarty .tpl
$this->ss->assign('JSON_CONFIG_JAVASCRIPT', $JavaScript);
parent::display();
}
}

In the file modules/Calls/metadata/editviewdefs.php we have the following defined for the templateMeta->JavaScript value:
'JavaScript' => '<script type="text/JavaScript">{$JSON_CONFIG_JAVASCRIPT}</script>'
 
Here the $JSON_CONFIG_JAVASCRIPT Smarty variable was the result of a complex operation and not available via the vardefs.php file (i.e. there is no JSON_CONFIG_JAVASCRIPT declaration in the vardefs.php file).
Creating a Custom Sugar Field
Let's try to create a new type of field for rendering a YouTube video. In this example, we will use a custom text field in the Contacts module and then override the Detail View of the custom field in the metadata file to link to our YouTube video.
The process is as follows:
1)
Create a custom text field in the Contacts module from the Studio editor
2)
Add this custom text field to both the Edit View and Detail View layouts
3)
Save and deploy both the updated layouts.
4)
Create a directory include/SugarFields/Fields/YouTube. The name of the directory (YouTube) corresponds to the name of the field type you are creating.
5)
In include/SugarFields/Fields/YouTube directory, create the file DetailView.tpl. For the DetailView we will use the "embed" tag to display the video. In order to do this, you need to add the following to the template file:
{if !empty({{sugarvar key='value' string=true}})}
<object width="425" height="350">
<param name="movie" value="http://www.youtube.com/v/{{sugarvar key='value'}}></param>
<param name="wmode" value="transparent"></param>
<embed src="http://www.youtube.com/v/{{sugarvar key='value'}}" type="application/x-shockwave-flash"
wmode="transparent" width="425" height="350">
</embed>
</object>
{/if}

You will notice that we use the "{{" and “}}” double brackets around our variables. This implies that that section should be evaluated when we are creating the cache file. Remember that Smarty is used to generate the cached templates so we need the double brackets to distinguish between the stage for generating the template file and the stage for processing the runtime view.
Also note that will use the default EditView implementation that is provided by the base sugar field. This will give us a text field where people can input the YouTube video ID, so you do not need to create EditView.tpl. Also, we do not need to provide a PHP file to handle the SugarField processing since the defaults will suffice.
6)
Now go to custom/modules/Contacts/metadata/detailview.php and add a type override to your YouTube field and save. In this example, the custom field is named "youtube".
array (
'name' => 'youtube_c',
'type' => 'YouTube',
'label' => 'LBL_YOUTUBE',
),
 
Your custom field is now ready to be displayed. You can now find the ID value of a YouTube video to insert into the EditView, and render the video in the DetailView. Remember to set your system to Developer Mode, or delete the EditView.tpl or DetailView.tpl files in the cache/modules/Contacts directory.
Adding QuickSearch to a Custom Field
1.
Include the default configs from QuickSearchDefaults.php. Most of the time you can use the predefined configurations and scripts.
require_once('include/QuickSearchDefaults.php');
$qsd = new QuickSearchDefaults();
2.
Then set up the config for the input box you wish to have SQS. Account, Team, and User configs are available. The following configures SQS for account search on input box w/ id of 'parent_name', user and team in similar fashion with defaults.
$sqs_objects = array('parent_name' => $qsd->getQSParent(),
'assigned_user_name' => $qsd->getQSUser(),
'team_name' => $qsd->getQSTeam());
Notes on structure of config - replace the default parameters if they are different for the page.
o
method: Unless you make a new method on the JSON server, keep this as query.
o
populate_list: This defines the id's of the fields to be populated after a selection is made.
QuickSearch will map the first item of field_list to the first item of populate_list. ie. field_list[0] = populate_list[0], field_list[1] = populate_list[1].... until the end of populate list.
o
limit: reduce from 30 if query is large hit, but never less than 12.
o
conditions: options are like_custom, contains, or default of starts with
if using 'like_custom' also define 'begin'/'end' for strings to prepend or append to the user input
o
disable: set this to true to disable SQS (optional, useful for disabling SQS on parent types in calls for example)
o
post_onblur_function: this is an optional function to be called after the user has made a selection. It will be passed in an array with the items in field_list as keys and their corresponding values for the selection as values.
$sqs_objects = array('account_name' => // this is the id
array(
// the method on to use on the JSON server
'method' => 'query',
'modules' => array('Accounts'), // modules to use
'field_list' => array('name', 'id'), // columns to select
// id's of the html tags to populate with the columns.
'populate_list' => array('account_name', 'account_id'),
'conditions' => // where clause, this code is for any account names that have A WORD beginning with ...
array(array('name'=>'name','op'=>'like_custom','end'=>'%','value'=>''),
array('name'=>'name','op'=>'like_custom','begin'=>'% ','end'=>'%','value'=>'')),
'group' => 'or', // grouping of the where conditions
'order' => 'name', // ordering
'limit' => '30', // number of records to pull
'no_match_text' => $app_strings['ERR_SQS_NO_MATCH'] // text for no matching results
),
3.
Include the necessary javascript files if sugar_grp1.js is not already loaded on the page.
$quicksearch_js = '<script type="text/javascript" src="' . getJSPath('include/javascript/sugar_grp1.js') . '"></script>';
4.
Assign your config array to sqs_objects (important!)
$quicksearch_js .= '<script type="text/javascript" language="javascript">
sqs_objects = ' . $json->encode($sqs_objects) . '</script>';
5.
Add validation so that if there is no matching id for what the user has entered in an SQS field, an alert shows. This is for fields such as assigned users where the form must submit a valid ID.
$javascript->addToValidateBinaryDependency('account_name', 'alpha',
app_strings['ERR_SQS_NO_MATCH_FIELD'] .
$mod_strings['LBL_MEMBER_OF'], 'false', '', 'parent_id');
6.
Add id tags and class name to the input box. Note that the input box must have class="sqsEnabled"!
<input class="sqsEnabled" id="account_name" name='account_name' size='30' type='text' value="{ACCOUNT_NAME}">
<input id='account_id' name='account_id' type="hidden" value='{ACCOUNT_ID}'>
 
Having trouble? Take a look at the file module/Contacts/BusinessCard.php.
Removing Downloads Tab for Sugar Plug-ins
Sugar Enterprise and Professional editions now include a Downloads tab that appears on the User Preferences page. This tab lists links to download Sugar Plug-ins for Microsoft Office.  If you do not want to display the Downloads tab to administrators and users, you need to add a configuration parameter named disable_download_tab to the config_override.php file with the value set to true, as shown below.

$sugar_config['disable_download_tab'] = true;
Tips
This section provides some tips you will find useful in using the new MVC and metadata framework and to avoid pitfalls that you may run into from the subtle details of the metadata framework that sometimes cause frustration and confusion. Here are some common scenarios that you may have to address.
Grouping Required Fields Together
To group all required fields together all you need to do is set the config to:
$GLOBALS['sugar_config']['forms']['requireFirst'] = true;
Displaying data on EditViews with a read-only ACL setting
$GLOBALS['sugar_config']['showDetailData'] = true;
The field value specified in metadata does not appear
This usually happens when the user is attempting to specify a variable name in the module's class definition, but not in the vardefs.php file. For example, consider the Products module. In the Products.php class file there is the variable:
var $quote_name;
If you attempt to retrieve the value in your metadata file as follows:
...
array (
'quote_name',
'date_purchased',
)
...
You must also make sure that 'quote_name' is specified in the vardefs.php file:
'quote_name' =>
array (
'name' => 'quote_name',
'type' => 'varchar',
'vname' => 'LBL_QUOTE_NAME',
'source'=>'non-db',
'comment' => 'Quote Name'
)

This is because the metadata framework populates the Smarty variable $fields using the variables listed in the vardefs.php file. If they are not listed, there is no way for the metadata framework to know for sure which class variables have been set and are to be used. The metadata framework works in conjunction with ACL (Access Control Level) checks in the system and these are tied to fields defined in the vardefs.php file.
The field value specified in metadata does not appear but is in vardefs.php
This may occur if the variable in the module has not been initialized. The metadata framework invokes the fill_in_additional_detail_fields() method so be sure the values are either set in the constructor or in the fill_in_additional_detail_fields() method.
A good strategy to debug the Smarty templates that are generated via the metadata files is to check the cache/modules/<module> directory for the .tpl files (DetailView.tpl, EditView.tpl, etc.). Enable the Developer Mode setting under the Advanced panel found through the Admin ->System Settings link to allow for the Smarty templates to be regenerated on every request.
Creating New Sugar Dashlets
A Module View is the simplest Sugar Dashlet to create. This is a customizable ListView of a Sugar Dashlet. For this section we will use the MyAccountsDashlet as an example.
MyAccountsDashlet.php:
// include the base class
require_once('include/Dashlets/DashletGeneric.php');
// required for a seed bean
require_once('modules/Accounts/Account.php');
 
class MyAccountsDashlet extends DashletGeneric {
// takes an $id, and $def that contains the options/title/etc.
function MyAccountsDashlet($id, $def = null) {
require_once('MyAccountsDashlet.data.php');
parent::DashletGeneric($id, $def);
global $current_user, $app_strings;
$this->searchFields =
$DashletData['MyAccountsDashlet']['searchFields'];
$this->columns =
$DashletData['MyAccountsDashlet']['columns'];
// define a default title
if(empty($def['title'])) $this->title = ‘My Account Dashlet’;
$this->seedBean = new Account();
}
}
All the metadata for this Sugar Dashlet is defined in the constructor. $searchFields are the search inputs that can be applied to the view. Defining these here will tell which input fields to generate corresponding filters when the user configures the Sugar Dashlet. $columns define the available columns to the user. These contain the visible columns and the columns the user can make visible. Both columns and searchFields are defined in MyAccountsDashlet.data.php so that Studio can modify them easily.
A seed bean is also required.
MyAccountsDashlet.data.php:
$DashletData['MyAccountsDashlet']['searchFields'] =
array('date_entered' => array('default' => ''));
 
$DashletData['MyAccountsDashlet']['columns'] = array(
'name' => array(
'width' => '40',
'label' => ‘LBL_LIST_ACCOUNT_NAME’,
'link' => true, // is the column clickable
'default' => true // is this column displayed by default
),
'billing_address_state' => array(
'width' => '8',
'label' => 'LBL_BILLING_ADDRESS_STATE’)
);
This file along with the MyAccountsDashlet.meta.php file is enough to create a generic module view Sugar Dashlet (see below).
Custom Sugar Dashlets
Sugar Dashlets are more than generic module views. They can provide unlimited functionality and integration.
For this section we will use the JotPad Sugar Dashlet as an example. The JotPad is a simple note taking Sugar Dashlet. A user double clicks on the Sugar Dashlet and can enter any text in the Sugar Dashlet. When the user clicks outside of the textarea, the text is automatically saved via AJAX.
There are six files that define this Sugar Dashlet
1.
JotPadDashlet.php – JotPad Class
2.
JotPadDashlet.meta.php – metadata about the Sugar Dashlet
3.
JotPadDashlet.tpl – Display Template
4.
JotPadDashletOptions.tpl – Configuration template
5.
JotPadDashletScript.tpl - Javascript
6.
JotPadDashlet.en_us.lang.php – English Language file
JotPadDashlet.php:
// this extends Dashlet instead of DashletGeneric
class Dashlet extends Dashlet {
var $savedText; // users's saved text
var $height = '100'; // height of the pad
 
function JotPadDashlet($id, $def) {
$this->loadLanguage('JotPadDashlet'); // load the language strings
 
// load default text is none is defined
if(!empty($def['savedText']))
$this->savedText = $def['savedText'];
else
$this->savedText = $this->DashletStrings['LBL_DEFAULT_TEXT'];
// set a default height if none is set
if(!empty($def['height']))
$this->height = $def['height'];
 
// call parent constructor
parent::Dashlet($id);
// Dashlet is configurable
$this->isConfigurable = true;
// Dashlet has JavaScript attached to it
$this->hasScript = true;
// if no custom title, use default
if(empty($def['title']))
$this->title = $this->DashletStrings['LBL_TITLE'];
else
$this->title = $def['title'];
}
 
// Displays the Dashlet
function display() {}
// Displays the JavaScript for the Dashlet
function displayScript() {}
// Displays the configuration form for the Dashlet
function displayOptions() {}
 
// called to filter out $_REQUEST object when the
// user submits the configure dropdown
function saveOptions($req) {}
 
// Used to save text on textarea blur.
// Accessed via Home/CallMethodDashlet.php
function saveText() {}
}
JotPadDashletOptions.tpl:
<form name='configure_{$id}' action="index.php" method="post" onSubmit='return SUGAR.Dashlets.postForm("configure_{$id}", SUGAR.sugarHome.uncoverPage);'>
The important thing to note here is the onSubmit. All configure forms should have this statement to uncover the page to remove the configuration dialog.
NOTE: It is important to separate your JavaScript into a separate JavaScript file. This is because Sugar Dashlets are dynamically added to a page through AJAX. The HTML included into JavaScript is not evaluated when dynamically included.
It is important that all JavaScript functions are included in this script file. Inline JavaScript (<a href onclick=’’ etc) will still function. If the Sugar Dashlet has JavaScript and a user dynamically adds it to the page, the Sugar Dashlet will not be accessible until after the user reloads the page.
Therefore it is beneficial to use as many generic methods in Dashlet.js as possible (Dashlets.callMethod() specifically!).
JotPadDashletScripts.tpl:
{literal}<script>
// since the Dashlet can be included multiple times a page,
// don't redefine these functions
if(typeof JotPad == 'undefined') {
JotPad = function() {
return {
blur: function(ta, id) {}, // called when textarea is blurred
edit: function(divObj, id) {}, // called when textarea is dbl clicked
saved: function(data) {}, // callback for saving
}();
}
</script>{/literal}
 
Please refer to the file for more detail comments.
Packaging Custom Sugar Dashlets
To make a Sugar Dashlet Module installable, you will need to package with the following also included in the manifest.php files.
$installdefs = array( 'id'=> 'jotpad', 'Dashlets'=> array( array('name' => 'JotPad', 'from' => '<basepath>/JotPad', ), ), );
Refreshing the Sugar Dashlet Cache
To add a Sugar Dashlet to your SugarCRM installation, you can use the Module Loader to install your Sugar Dashlet Package. However, for development purposes, to make the Sugar Dashlet available to add to the home page you will need to run the Repair Sugar Dashlet Link in the Admin Repair Panel at least once after you have created the Dashlet.
This will rebuild the cache file /<cache dir>/Dashlets/Dashlets.php by scanning the folders /modules/ and /custom/modules/ for Dashlet Files.
Creating Custom Chart Dashlets
Creating a custom chart dashlet is very similar to how we created the MyAccountsDashlet above. The main difference is that you will need to override the display() method in your class to build the chart, using the SugarChart library included with SugarCRM. Below is an example display() method as used in the Outcome by Month dashlet.
public function display()
{
$currency_symbol = $GLOBALS['sugar_config']['default_currency_symbol'];
if ($GLOBALS['current_user']->getPreference('currency')){
require_once('modules/Currencies/Currency.php');
$currency = new Currency();
$currency->retrieve($GLOBALS['current_user']->getPreference('currency'));
$currency_symbol = $currency->symbol;
}
 
require("modules/Charts/chartdefs.php");
$chartDef = $chartDefs['outcome_by_month'];
require_once('include/SugarCharts/SugarChart.php');
$sugarChart = new SugarChart();
$sugarChart->setProperties('',
translate('LBL_OPP_SIZE', 'Charts') . ' ' . $currency_symbol . '1' .translate('LBL_OPP_THOUSANDS', 'Charts'),
$chartDef['chartType']);
$sugarChart->base_url = $chartDef['base_url'];
$sugarChart->group_by = $chartDef['groupBy'];
$sugarChart->url_params = array();
$sugarChart->getData($this->constructQuery());
$xmlFile = $sugarChart->getXMLFileName($this->id);
$sugarChart->saveXMLFile($xmlFile, $sugarChart->generateXML());
return $this->getTitle('<div align="center"></div>') .
'<div align="center">' . $sugarChart->display($this->id, $xmlFile, '100%', '480', false) . '</div><br />';
}
 
protected function constructQuery()
{
$query = "SELECT sales_stage,".
db_convert('opportunities.date_closed','date_format',array("'%Y-%m'"),array("'YYYY-MM'"))." as m, ".
"sum(amount_usdollar/1000) as total, count(*) as opp_count FROM opportunities ";
$query .= " WHERE opportunities.date_closed >= ".db_convert("'".$this->obm_date_start."'",'datetime') .
" AND opportunities.date_closed <= ".db_convert("'".$this->obm_date_end."'",'datetime') .
" AND opportunities.deleted=0";
if (count($this->obm_ids) > 0)
$query .= " AND opportunities.assigned_user_id IN ('" . implode("','",$this->obm_ids) . "')";
$query .= " GROUP BY sales_stage,".
db_convert('opportunities.date_closed','date_format',array("'%Y-%m'"),array("'YYYY-MM'")) . " ORDER BY m";
return $query;
}
Themes
The goal of the Themes framework is to reduce the complexity of the current themes and the amount of work needed to create new themes in the product. The framework also provides tools for easily changing a theme in an upgrade-safe way without modifing the theme directly. This is all possible through an inheritance mechanism that is part of the framework, where themes can build upon other themes to build the user interface for the application. This directly reduces the duplication of code in the application, and enables new UI elements to be supported more easily in any theme.
Theme Directory Structure
The theme directory has a more formal structure to it, which must be followed in order for the inheritance mechanism in the themes framework to work correctly. It is as follows:
themes/
<theme name>/
themedef.php
css/ // all css files go here
style.css
print.css
images/ // all images go here
js/ // all js files go here
The themedef.php file specified also has a specific format to it so that it can be interpreted properly by the application. It is as follows:
$themedef = array(
'name' => "Sugar", // theme name
'description' => "Sugar", // short description of the theme
'maxTabs' => $max_tabs, // maximum number of tabs shown in the bar
'pngSupport' => true, // true if png image files are used in this theme, false if gifs
'parentTheme' => "ParentTheme", // name of the theme this theme inherits from, if something other than the default theme.
'barChartColors' => array(....),
'pieChartColors' => array(....),
);
Please note that only the 'name' specification is required; all other elements are optional.
Theme Development
When you are developing a new theme or adding modifications to an existing theme, it is recommended to turn developer mode on in the 'System Settings' in the 'Admin' section of the application. This is so that any changes you make will become immediately visible to you, making testing you changes easier. Once the theme development is complete, it is recommended that you turn off the Developer Mode.
The theme framework performance is greatly enhanced with the use of an external caching mechanism such as APC or Memcache. It is highly recommended to have this in place.
Changing a Theme
Modifications to any theme in the application can be made in the custom/themes/ directory under the theme in question. For example, to replace the default Accounts.gif image in the Sugar theme, drop the new.gif image file into the custom/themes/<theme name>/images/ directory. You can do the same for CSS and JS files; in these cases the given files will be appended to the existing ones instead of being used in place of them.
The order in which directories are searched for overriding images/css/js files is as follows:
1. custom/themes/<theme name>/
2. themes/<theme name>/
3. any parent themes ( custom directory first, then regular one )
4. custom/themes/default/
5. themes/default/
Creating a New Theme
The easiest way to create a new theme is to find a base themes that you like and base your design on it. This reduces the amount of CSS work you'll have to do on your own, and you can rest assured that any theme fixes will also be fixed in your theme, thanks to inheritance. To do this, you'll need to create a themedef.php file with the following specifications in it:
$themedef = array(
'name' => "MySugar", // theme name
'description' => "Sugar theme for me", // optional, short description of the theme
'parentTheme' => "Sugar", // name of the theme this theme inherits from, in this case the Sugar theme
);
You can now add any CSS, images, and/or JS code to their respective directories to make the needed alterations to the parent theme to create the desired theme. It is by no means a requirement to derive a theme from one of the existing ones in the product; if you do not specify the 'parentTheme' attribute above, then the theme settings in the themes/default/ directory will be used.
Element Reference Guide
Below is a guide of the various id elements and classes that are used in the application. IDs are indicated below where they are prefixed by a # sign ( i.e. #dog for the ID dog ), and classes are specified by a '.' ( .cat for class cat ).
.edit
EditView containers
.detail
DetailView containers
.list
ListView containers
.view
Styles for any of the detail, edit. list, and search view containers
.search
Search container
 
The below figure illustrates the where the main UI div elements are located and what their IDs are.
 
 
Packaging Custom Themes
The Upgrade Wizard, accessible through the Admin screen, allows you to apply themes without unzipping the files manually. The theme is also actually added to the “Theme” dropdown on the Sugar Login screen.
The Upgrade Wizard relies on a file named manifest.php, which should reside alongside the root directory of your theme ZIP file.
The following section outlines the format of the manifest file. An example manifest file can be found in the following section.
o
acceptable_sugar_flavors Contains which Sugar Editions the package can be installed on. Accepted values are any combination of: CE, PRO, and ENT.
o
acceptable_sugar_versions This directive contains two arrays:
o
exact_matches: each element in this array should be one exact version string, i.e. “6.0.0b” or “6.1.0”
o
regex_matches: each element in this array should be one regular expression designed to match a group of versions, i.e. “6\\.1\\.0[a-z]”
o
author Contains the author of the package; for example, “SugarCRM Inc.”
o
copy_files An array detailing the source and destination of files that should be copied during installation of the package. See the example manifest file below for details.
o
description A description of the package. Displayed during installation.
o
icon A path (within the package ZIP file) to an icon image that will be displayed during installation. Examples include “./patch_directory/icon.gif” and “./patch_directory/images/theme.gif”
o
is_uninstallable Setting this directive to TRUE allows the Sugar administrator to uninstall the package. Setting this directive to FALSE disables the uninstall feature.
o
name The name of the package. Displayed during installation.
o
published_date The date the package was published. Displayed during installation.
o
type The package type. This should be set to “theme”
o
version The version of the patch, i.e. “1.0” or “0.96-pre1”
Example Theme Manifest File
The following is an example manifest.php file:
<?php
$manifest = array (
'acceptable_sugar_versions' =>
array (
'exact_matches' =>
array (
),
'regex_matches' =>
array (
0 => '3.5.[01][a-z]?'
),
),
'acceptable_sugar_flavors' =>
array (
0 => 'OS',
1 => 'PRO',
2 => 'ENT',
),
'name' => 'Theme Name',
'description' => 'Theme Description’,
'author' => 'SugarCRM Inc.',
'published_date' => '2005-09-15 16:00:00',
'version' => '3.5.1',
'type' => 'theme',
'is_uninstallable' => TRUE,
'icon' => 'ThemeName/images/Themes.gif',
'copy_files' =>
array (
'from_dir' => 'ThemeName',
'to_dir' => 'themes/ThemeName',
'force_copy' =>
array (
),
),
); ?>
Example File Structure: The following is an example of the file structure of the GoldenGate theme:
ThemeName.zip
| manifest.php | \---ThemeName
| config.php
| cookie.js
| footer.php
| <more files>
|
\---images
accept_inline.gif
AccountReports.gif
Accounts.gif
<more images>
 
You’ll need to create a root directory that contains the theme directory. The name of this root directory (ThemeName) is what should be used in the from_dir element of the copy_files array in manifest.php. You’ll also need to place your manifest.php alongside this root directory. Create a ZIP file containing the root directory and the manifest.php file at the top level. Now your language pack is ready to be installed with the Upgrade Wizard.
Tips
Pick your Canvas
Think about how you want the general look and feel of your theme, and see which out-of-the-box existing Sugar theme best fits. This will reduce any extra work that may come out of rearranging the layout because you chose the first theme you saw.
Replace All
When changing colors in the css files, do a “replace all” on the file. For example, if you are changing the color ‘#FF0000’ to ‘#CC0000’, change all instances of ‘#FF0000’ to ‘#CC0000’. Eventually you will get to a point where you may want your changes to only affect one class, and may have to go back and refine some of the mass changes. However doing this initially will usually yield favorable results, and save you some time.
Check your work
So you have all your css laid out and your home page looks good? Did you check your Edit and List views? Did you check the calendar popup widgets (from date fields)? Often, developers forget to check the css for Sugar Dashlets, reports and charts. Do not forget to do a thorough check, and keep in mind that you may have to tweak with navigation.css, layout_utils.php, and sugarColors.xml files before being finally done.
Personalize your theme
Remember this is your theme now. If you want to add a new div, or introduce a new class, you do not have to make it fit within the confines of the theme with which you started. Most of the images are transparent and work fine, but changing the look and feel of those would add an extra degree of customization. So, go ahead and add your flash intro, embedded mp3 or Star Wars Background.
Adding Multiple Languages
Sugar as an application platform is internationalized and localizable. Data is stored and presented in the UTF8 codepage allowing for all character sets to be used. Sugar provides a language pack framework allowing developers to build support for any language to be used in the display of user interface labels.
Adding a language is a simple process. Two solutions exist to add your own language to SugarCRM.
When you add a new language, you must choose a language prefix. While you can choose any key value you want, we recommend following the standard locale naming convention. For example, en_en for English, en_us for US English, ge_ge for German or ge_ch for Swiss German. This key value will be the prefix for all of your new language files.
Add a Language
You can add a new language directly to Sugar without using a Language Pack.
Follow the steps outlined below:
1.
Add the new language you are creating to the $languages variable in the config.php file. For instance, to add Spanish, first modify the config.php file in the root of your Sugar installation to reference the new language pack.
$sugar_config[`languages`] = array('en_us'=>'US English','es_es'=>'Espanol’);
 
Note: You can also set the default language in the config.php. This value is used if a user does not specify a language while logging into the application.
2.
Cut and paste each of the en_us.lang.php string files that ship with Sugar Open Source into a new file (<new>.lang.php) with the new prefix you set in the step above.
There are two general locations where you will need to create the new language files:
o
include/language/<new>.lang.php - This file contains the strings common across the entire application. This file must exist for each language defined in config.php.
o
modules/<some_module>/language/<new>.lang.php - These files contain the strings specific to each module.
Note: Some language files that ship with Sugar are not named “en_us.lang.php” but are “.html” or “.tpl” files. These files are used for the inline help system. A complete language pack will include the translated versions of these files as well.
3.
After you create your new files by cutting and pasting the en_us.lang.php files, open each file and translate the strings from English. The strings are defined inside of global arrays and the array syntax does need to be maintained for everything to work. A common problem you will quickly see if the array syntax is off is that the user interface doesn't display at all (just a blank page).
Note: In the include/language/<new>.lang.php file, you will see that there are two global arrays defined. The $app_list_strings array is actually an array of arrays. The key values in this array must not be changed. There are comments and examples in the code that should keep you on track.
Creating Language Packs
A Language Pack is a compressed file loadable through Module Loader. It is the best solution to add a language to SugarCRM. Indeed, it is easier to maintain and to port to other instances of SugarCRM. By default, the Help link in the Sugar application points to the Sugar Application Guide. If you want the Help link in Sugar to point to localized Help content in a language other than English, you can include your localized inline Help files in the language pack.
There are different ways to create a Language Pack:
•
You can build a Language Pack using one of the tools available on SugarForge like “SugarCRM Translation Module” or “Sugar Translation Suite”.
•
You can create it using an existing Language Pack:
o
Download an existing Language Pack.
Note: Be careful to choose a language pack that is up to date and is working.
o
Uncompress it and be careful to keep the folder architecture.
o
Rename all the files with a name starting with the language prefix (for example “es_es” if you downloaded the Spanish Language Pack) by replacing the old prefix (“es_es”) with the prefix of your new language. Be careful to not modify the manifest.php file and the name of the folders.
o
Open each file that you have renamed and translate the strings from English. The strings are defined inside of global arrays, and the array syntax does need to be maintained for everything to work. A common problem you will see if the array syntax is off is that the user interface does not display at all (just a blank page).
o
Optionally, include localized Help files for each view in each module. For example, for the Portugese (Brazilian) language pack, you would include pt_br.help.index.html (for List View), pt_br.help.DetailView.html (for Detail View), and pt_br.help.EditView.html (for Edit View).
o
Modify the manifest.php file based on the file changes you made.
o
Compress back everything in a zip file.
o
You can now load this Language Pack using Module Loader.
•
You can create it from the start to finish:
o
Follow the steps of “Add a Language” above.
o
After you ensure that it works on your test instance, package it to be installed.
o
Module Loader allows you to apply language packs without needing to add the language to the $languages array in config.php. The Module Loader relies on a file named manifest.php, which should reside alongside the root directory of your language pack ZIP file.
The following is an example manifest.php file, for the Portugese (Brazilian) language pack:
<?php
$manifest = array (
'acceptable_sugar_versions' =>
array (
'exact_matches' =>
array (
),
'regex_matches' =>
array (
0 => '5\.0\.0[a-z]?'
),
),
'acceptable_sugar_flavors' =>
array (
0 => 'CE',
1 => 'PRO',
2 => 'ENT',
),
'name' => 'Portugese (Brazilian) language pack',
'description' => 'Portugese (Brazilian) language pack',
'author' => 'Your name here!',
'published_date' => '2008-07-29 22:50:00',
'version' => '5.0.0',
'type' => 'langpack',
'icon' => '',
'is_uninstallable' => TRUE,
),
$installdefs = array(
'id' => 'pt_br',
'copy' => array(
array(
'from' => '<basepath>/modules',
'to' => 'modules',
),
array(
'from' => '<basepath>/include/language'),
'to' => 'include/language'
),
array(
'from' => '<basepath>/install/language',
'to' => 'install/language',
),
),
);
 
?>
The following is an example of the file structure of the Portugese (Brazilian) language pack:
SugarEnt-5.0.0-lang-pt_br-2008-07-29.zip
|
manifest.php
|
|___ include
| |___language
| pt_br.lang.php
|
|___ modules
|
|___ Accounts
| |
| |___ language
| pt_br.lang.php
|
|___ Activities
| |___ language
| pt_br.lang.php
|
|___ <other module directories>
 
You will need to create a root directory that contains the ./include/ and ./modules/ directories of the language pack.
The name of this root directory (i.e. pt_br_500) is what should be used in the from_dir element of the copy_files array in manifest.php. You will also need to place your manifest.php alongside this root directory.
Then you must copy all the language files that you created as described in “Add a Language” into these directories. Be careful to keep the same directory structure (for examples if the file was in modules/Accounts/language copy/paste it in pt_br_500/modules/Accounts/language).
Create a Zip file containing the root directory and the manifest.php file at the top level. Now your language pack is ready to be installed with the Module Loader.
Creating a Connector
This section describes how to write a connector that can be installed through the Module Loader.
1)
Create project directory and files.
The first step is to create a project directory for your connector. We can call this connector "test" for now and create a directory called "test". Under the "test" directory, also create a sub-directory called "source" and then under the "source" directory, create another sub-directory "language". The "source" directory will contain your connector's code. The minimal files a connector should provide are a config file (config.php), a variable definition file (vardefs.php) and a connector source file (test.php in this case). An optional default mapping file that associates your connector's fields with fields in Sugar's modules may be provided (mapping.php). Your directory should look like this:
test
test/source
test/source/test.php
test/source/vardefs.php
test/source/config.php
test/source/mapping.php (optional)
 
test/language
test/language/en_us.lang.php (default English language file for localization)
2)
Create the vardefs.php file.
The next step is to provide a list of variable definitions that your connector uses. These should be the fields that your connector uses. For example, if your connector is a person lookup service, then these fields may be a first and last name, email address and phone number. You must also provide a unique field identifier for each connector record. This unique field needs to be named "id". Each vardef field entry is a defined within a PHP Array variable. The syntax is similar to a Sugar module's vardefs.php file with the exception of the 'hidden', 'input', 'search', 'hover' and 'options' keys.
The 'hidden' key/value parameter is used to hide the connector's field in the framework. The required "id" field should be declared hidden because this is a unique record identifier that is used internally by the connector framework.
The 'input' key/value parameter is an optional entry to provide an input argument name conversion. In other words, if your connector service expects a "firstName" argument but your connector's field is named "firstname", you may provide an additional input entry so that the connector framework will call your connector's getItem() and getList() methods with an argument named "firstName". Typically, the 'input' key/value parameter is used to support searching.
'lastname' => array (
'name' => 'lastname',
'vname' => 'LBL_LAST_NAME',
'input' => 'lastName',
'search' => true,
'hover' => 'true',
),
Although the benefit of this is probably not captured well in this example, you could potentially have a service that groups arguments in a nested array. For example imagine the following array of arguments for a connector service:
$args['name']['first']
$args['name']['last']
$args['phone']['mobile']
$args['phone']['office']
Here we have an array with 'name' and 'phone' indexes in the first level. If your connector expects arguments in this format then you may supply an input key/value entry in your vardefs.php file to do this conversion. The input key value should be delimited with a period (.).
'lastname' => array (
'name' => 'lastname',
'vname' => 'LBL_LAST_NAME',
'input' => 'name.last', // Creates Array argument ['name']['last']
'search' => true,
'hover' => 'true',
),

The 'search' key/value parameter is an optional entry used to specify which connector field(s) are searchable. In step 1 of the connector wizard screen, a search form will be generated for your connector so that the user may optionally refine the list of results shown. Currently, we do not filter the fields that may be added to the search form so the use of the 'search' key/value parameter serves more as a visual indication.
The 'hover' key/value parameter is an optional entry to support the hover functionality. A vardef field that is denoted as the hover field contains the value the hover code will use in displaying a popup that displays additional detail in the Detail Views.
The 'options' key/value parameter allows the developer to map values returned by the connector to values that may be used by the Sugar database. In our example, the state field returns the abbreviated value of the State (CA for California, HI for Hawaii, etc.). If we wish to use the State name instead of the abbreviated name, we may specify the 'options' key/value parameter and then add the mapping entry (mentioned in step 9) to enable this translation. This is especially helpful should your system depend on a predefined set of values that differ from those returned by the connector.
Here is a complete example of our "test" connector’s vardefs.php file:
<?php
$dictionary['ext_rest_test'] = array(
'comment' => 'A test connector',
'fields' => array (
'id' => array (
'name' => 'id',
'vname' => 'LBL_ID',
'hidden' => true,
),
'firstname' => array (
'name' => 'firstname',
'vname' => 'LBL_FIRST_NAME',
),
'lastname'=> array(
'name' => 'lastname',
'vname' => 'LBL_LAST_NAME',
'input' => 'name.last',
'search' => true,
),
'website'=> array(
'name' => 'website',
'vname' => 'LBL_WEBSITE',
'hover' => true,
),
'state'=> array(
'name' => 'state',
'vname' => 'LBL_STATE',
'options' => 'states_dom',
),
)
);
?>
3)
Create the config.php file.
The config.php file holds a PHP array with two keys. The "name" is used to provide a naming label for your connector that will appear in the tabs throughout the application. The "properties" key may be used to store runtime properties for your connector. Here we have simply provided the name "Test" and a properties value that we may use to control the maximum number of results we return in our connector.
<?php
$config = array (
'name' => 'Test',
'properties' =>
array (
'max_results' => 50,
),
);
?>
4)
Create the Language file contents.
The next step is to create a language file with labels for your application. Notice that the properties defined in the config.php file are indexed by the property key ("max_results"). Otherwise, the vardefs.php entries should be indexed off the "vname" values.
<?php
$connector_strings = array (
//vardef labels
'LBL_FIRST_NAME' => 'First Name',
'LBL_LAST_NAME' => 'Last Name',
'LBL_WEBSITE' => 'Website',
'LBL_STATE' => 'State',
//Configuration labels
'max_results' => 'Maximum Number of Results',
);
?>
5)
Determine the connector protocol type.
The second step is to determine the connector protocol type to create the connector source file. Currently the two Web Services protocols supported are REST and SOAP. If the web service is a REST protocol, then the connector should extend the ext_rest class defined in the file include/connectors/sources/ext/rest/rest.php. If the web service is a SOAP protocol, then the connector should extend the ext_soap class defined in the file include/connectors/sources/ext/soap/soap.php. In this example, we will extend the ext_rest class. The class name should contain the "ext_rest_" suffix if it is a REST protocol connector or "ext_soap_" if it is a SOAP protocol connector.
<?php
require_once('include/connectors/sources/ext/rest/rest.php');
class ext_rest_test extends ext_rest {
 
}
?>
6)
Provide implementations for the getItem() and getList() Methods.
There are two methods that a connector must override and provide an implementation for. These are the getItem() and getList() methods. These two methods are called by the component class (include/connectors/component.php). The getList() method as its name suggests, returns a list of results for a given set of search criteria that your connector can handle. On the other hand, the getItem() method should attempt to return a single connector record. For example, if your connector is a person lookup service, the getList() method may return matching person values based on a first and last name search. The getItem() method should return values for a unique person. Your service may uniquely identify a person based on an internal id or perhaps an email address.
The getList() method accepts two arguments. $args is an Array of argument values and $module is a String value of the module that the connector framework is interacting with. The getList() method should return a multi-dimensional Array with each record's unique id as the key. The value should be another Array of key/value pairs where the keys are the field names as defined in the vardefs.php file.
public function getList($args=array(), $module=null) {
 
$results = array();
 
if(!empty($args['name']['last']) && strtolower($args['name']['last']) == 'doe') {
$results[1] = array('id'=>1, 'firstname'=>'John', 'lastname'=>'Doe', 'website'=>'www.johndoe.com', 'state'=>'CA');
$results[2] = array('id'=>1, 'firstname'=>'Jane', 'lastname'=>'Doe', 'website'=>'www.janedoe.com', 'state'=>'HI');
}
 
return $results;
 
}
The getItem() method also accepts two arguments. $args is an Array of argument values and $module is a String value of the module that the connector framework is interacting with. The getItem() method will be called with a unique id as defined in the getList() method's results.
public function getItem($args=array(), $module=null) {
$result = null;
if($args['id'] == 1) {
$result = array();
$result['id'] = '1'; //Unique record identifier
$result['firstname'] = 'John';
$result['lastname'] = 'Doe';
$result['website'] = 'http://www.johndoe.com';
$result['state'] = 'CA';
} else if($args['id'] == 2) {
$result = array();
$result['id'] = '2'; //Unique record identifier
$result['firstname'] = 'Jane';
$result['lastname'] = 'Doe';
$result['website'] = 'http://www.janedoe.com';
$result['state'] = 'HI';
}
return $result;
}
7)
Provide optional testing functionality
This is an optional step where you may wish to provide functionality for your connector so that it may be tested through the administration interface under the "Set Connector Properties" section. To enable testing for your connector, set the connector class variable _has_testing_enabled to true in the constructor and provide a test () method implementation.
public function __construct(){
parent::__construct();
$this->_has_testing_enabled = true;
}
 
public function test() {
$item = $this->getItem(array('id'=>'1'));
return !empty($item['firstname']) && ($item['firstname'] == 'John');
}
8)
Provide optional Hover Link functionality
This is an optional step where you may wish to provide functionality for your connector so that the DetailView of modules enabled for the connector display a popup with additional information. Depending on the connector field, this step involves creating some additional PHP and Smarty code. A new directory needs to be created to contain the hover code.
Create a "formatter" sub-directory under the "Test" connector's root folder. Then add the formatter class there. We'll also call this file "test.php". Also create a "tpls" sub-directory under the "formatter" directory. The "tpls" directory may contain an optional icon that will be displayed next to the field in the DetailView that will activate the hover popup. By default, the connector framework uses the icon in themes/default/images/icon_Connectors.gif. The default.tpl file is the Smarty template file that will be activated when the hover icon is launched. Your directory structure should now appear as:
test
 
test/source
test/source/test.php
test/source/vardefs.php
test/source/config.php
test/source/mapping.php (optional)
 
test/language
test/language/en_us.lang.php (default English language file for localization)
 
test/formatter
test/formatter/test.php
test/formatter/tpls/test.gif
test/formatter/tpls/default.tpl
 
The test.php file should extend default_formatter (include/connectors/formatters/default/formatter.php) with the same prefix naming convention used for the connector class "ext_rest_" in this case. Also, place the prefix "_formatter" after the name of the connector. In our example, we are looking for Sugar module fields that have been mapped to the website connector field. If a module field displayed in the Detail View has been mapped to our connector's website field then we will add the code to display the hover popup.
<?php
class ext_rest_test_formatter extends default_formatter {
 
public function getDetailViewFormat() {
$mapping = $this->getSourceMapping();
$mapping_name = !empty($mapping['beans'][$this->_module]['website']) ? $mapping['beans'][$this->_module]['website'] : '';
 
if(!empty($mapping_name)) {
$this->_ss->assign('mapping_name', $mapping_name);
return $this->fetchSmarty();
}
 
$GLOBALS['log']->error($GLOBALS['app_strings']['ERR_MISSING_MAPPING_ENTRY_FORM_MODULE']);
return '';
}
public function getIconFilePath() {
return 'custom/modules/Connectors/connectors/formatters/ext/rest/test/tpls/test.jpg';
}
 
}
?>
The default.tpl file should contain the code to display additional information. The connector framework will trigger a call to the show_ext_rest_[connector name] or show_ext_soap_[connector_name] methods depending on the connector type (REST or SOAP) when a mouseover javascript action is detected on the hover field (single icon) or when a mouseclick javascript action is detected on the hover field (multiple hover links shown in dropdown menu).
We provide a simple example below, but typically you may wish to have the hover code make additional calls to retrieve information. For example, you may wish to use an AJAX pattern to make a request back to the Sugar system that will in turn make a REST call to your connector.
<div style="visibility:hidden;" id="test_popup_div"></div>
<script type="text/javascript">
function show_ext_rest_test(event)
{literal}
{
 
var xCoordinate = event.clientX;
var yCoordinate = event.clientY;
var isIE = document.all?true:false;
if(isIE) {
xCoordinate = xCoordinate + document.body.scrollLeft;
yCoordinate = yCoordinate + document.body.scrollTop;
}
 
{/literal}
 
cd = new CompanyDetailsDialog("test_popup_div", 'This is a test', xCoordinate, yCoordinate);
cd.setHeader("{$fields.{{$mapping_name}}.value}");
cd.display();
{literal}
}
{/literal}
</script>
You will now need to set the class variable _enable_in_hover to true in the connector's constructor in test/source/test.php:
public function __construct(){
parent::__construct();
$this->_has_testing_enabled = true;
$this->_enable_in_hover = true;
}
9)
Provide optional mapping.php file.
This is another optional step where you may provide optional mapping entries for select modules in Sugar. In our vardefs.php file example in step 2, we enabled the hover link for the website field. To explicitly place this hover link on the website field for the Accounts module we provide the mapping entry as follows. A mapping.php file is needed though if you use the 'options' attribute for entries in the vardefs.php file.
<?php
$mapping = array (
'beans' =>
array (
'Accounts' =>
array (
'website' => 'website',
),
),
//options mapping
'options' =>
array (
'states_dom' =>
array(
'CA' => 'California',
'HI' => 'Hawaii',
),
),
);
?>
10)
Package your connector.
The final step would be to zip your connector's contents along with a manifest.php file so that it may be installed by the Module Loader. Place the manifest.php file into folder that includes the "test" directory. Your zip file should have the following directory structure:
test/source/test.php
test/source/vardefs.php
test/source/config.php
test/source/mapping.php
 
test/language/en_us.lang.php
 
test/formatter/test.php
test/formatter/tpls/test.jpg
test/formatter/tpls/default.tpl
 
../test/manifest.php <--- in the folder that contains the "test" folder
A sample manifest.php file is as follows:
<?php
$manifest = array(
'acceptable_sugar_flavors' => array(
'CE',
'PRO',
'ENT',
),
'acceptable_sugar_versions' => array(
'5.2.0',
),
'is_uninstallable' => true,
'name' => 'Test Connector',
'description' => 'Connector for testing purposes only',
'author' => 'John Doe',
'published_date' => '2008/12/12',
'version' => '1.0',
'type' => 'module',
'icon' => '',
);
 
$installdefs = array (
'id' => 'ext_rest_test',
'connectors' => array (
array (
'connector' => '<basepath>/test/source',
'formatter' => '<basepath>/test/formatter',
'name' => 'ext_rest_test',
),
),
 
);
 
?>
Dynamic Teams
Dynamic Teams provides the ability to assign a record to multiple teams. This provides more flexibility in sharing data across functional groups.
Database Changes
The Sugar Professional and Sugar Enterprise versions create four new tables (team_hierarchies, team_sets, team_sets_modules and team_sets_teams). A description of each table is as follows:
Table
Description
team_hierarchies
Not used currently, but added to provide future support for team hierarchies.
team_sets
Each record in this table represents a unique team combination. For example, each user’s private team will have a corresponding team set entry in this table. A team set may also be comprised of one or more teams.
team_sets_teams
The team_sets_teams table maintains the relationships to determine which teams belong to a team set. Each table that previously used the team_id column to maintain team security now uses the team_set_id column’s value to associate the record to team(s).
team_sets_modules
This table is used to manage team sets and keeps track of which modules have records that are or were associated to a particular team set.
In addition to the four new tables, each table that previously used the team_id column to store the team access information will now have a new team_set_id column to record the team set id value. This is also true in the case of upgrades from pre-5.5.x versions. However, custom modules created using the CE editions of the system that go through the flavor conversion to the PRO/ENT editions will not be upgraded to support teams. In such situations, it will still be the responsibility of the developer to provide the team security feature through Module Builder.
Team Security
The team_sets_teams table allows the system to check for permissions on multiple teams. The following diagram illustrates table relationships in SugarBean’s add_team_security_where_clause method.
team_security_diagrm
Using the team_sets_teams table the system will determine which teams are associated with the team_set_id and then look in the team_memberships table for users that belong to the team(s).
Overview
On every Edit View screen, the user should be presented with a Teams widget which provides the ability to associate one or more teams to the record. The user can either perform a quick search to associate a team or they can select one or many teams from the popup. When the record is saved a team_set_id is associated to the record. A team set is simply a unique combination of teams. Sugar could have implemented Dynamic Teams as a many-many relationship in the database, but the idea of team sets takes advantage of combinations of teams that are re-used throughout the system. Rather than replicated sets of teams each time we create a record, we simply re-use the team_set_id thereby reducing the amount of duplicated data.
Team Sets
As mentioned above, Sugar implemented this feature not as a many-to-many relationship but as a one-to-many relationship. On each table that had a ‘team_id’ field we added a ‘team_set_id’ field. We have also added a ‘team_sets’ table which maintains the team_set_id, a ‘team_sets_teams’ table which relates a team set to the teams. When performing a team based query we use the ‘team_set_id’ field on the module table to join to ‘team_sets_teams.team_set_id’ and then join all of the teams associated with that set. Given the list of teams from team_memberships we can then decide if the user has access to the record.
Primary Team
The ‘team_id’ is still being used, not only to support backwards compatibility with workflow and reports but also to provide some additional features. When displaying a list we use the team set to determine whether the user has access to the record, but when displaying the data, we show the team from team id in the list. When the user performs a mouse over on that team Sugar performs an Ajax call to display all of the teams associated with the record. This ‘team_id’ field is designated as the Primary Team because it is the first team shown in the list, and for sales territory management purposes, can designate the team that actually owns the record and can report on it.
Adding Teams Programatically
To add teams to a record, you may first load the teams relationship on SugarBean and then pass in an Array of team ids to the add method.
…
$contact->load_relationship(‘teams’);
$contact->teams->add(array(‘East’, ‘West’));
…
If there are already other teams assigned to this contact, the system will check to see if an entry in the team_sets table exists for the combination of teams specified. It will create entries in the team_sets and team_sets_teams tables if necessary to record the unique combination of teams. In addition, if you have a team_id value that is not in the list of teams in the set, then it will be added.
An example of the SOAP API to set teams is as follows
…:
//Create nusoapclient
$this->_soapClient = new nusoapclient($soap_url);
//Login
$result = $this->_soapClient->call('login', …);
$session_id = $result['id'];
$this->_soapClient->call('set_relationship',array('session'=>$this->_$session_id,'module_name'=>'Contacts', 'module_id'=>$contact_id, 'link_field_name' => 'teams', 'related_ids' => array('1', 'East', 'West')));
…
It is important to note that when adding teams, additional teams that are not specified programmatically can be added. This will be the case if a person assigned to a record does not belong to any of the teams that will be associated with the record. In this scenario, we will add the assigned–to- user’s private team into the list of teams. If you wish to disable this behavior, you can edit the system’s config.php file and add the following entry:
‘disable_team_access_check’ => true
Removing Teams Programmatically
Removing teams is pretty simple. As before, you load the Teams relationship:
$contact->load_relationship(‘teams’);
$contact->teams->remove(array(‘team1’, ‘team2’));

One thing to note is that if one of the teams you are removing is the primary team as defined by the team_id column, then Sugar logs this and prevents the removal of this team. Because Sugar does not know what to do next if the primary team is removed, we prevent this action.
Replacing Teams Programmatically
As is often the case you may just want to replace all of the teams you have on a record so we have provided the replace method:
$contact->load_relationship(‘teams’);
$contact->teams->replace(array(‘team1’, ‘team2’));
TeamSetLink
You can define your own Link class. Typically any relationship in a class is handled by the data/Link.php class. As part of Dynamic Teams, we introduced the ability to provide your own custom Link class to handle some of the functionality related to managing relationships. The team_security parent vardefs in SugarObjects contains the following in the ‘teams’ field definition:
…
'link_class' => 'TeamSetLink',
'link_file' => 'modules/Teams/TeamSetLink.php',

The link_class entry defines the class name we are using and the link_file tells us where that class file is located. This class should extend Link.php and you can then override some of the methods used to handle relationships such as ‘add’ and ‘delete’.
The Dynamic Teams WidgetPicture 4
The only reason we present the widget here is to outline how each element in this widget is associated with an element in the system. This widget is rendered in place of the Teams relationship field. However, the old Teams relationship field will still work.
The Primary radio button will select the team which will be saved to the team_id field on the record. Every other field will be added as a team associated with the team set. Adding or removing teams here will result in this record being assigned a new team set. The team set may already exist, and if so that id is simply assigned to the record.
Printing to PDF
The OOB Quotes and Reports modules allow users to generate output in PDF format. Sugar uses theTCPDF engine in order to extend automatic PDF support for a much larger set of languages.
SugarPDF Architecture
The new PDF framework leverages the SugarCRM MVC architecture.
 
SugarpdfDiag
 
Key Classes
ViewSugarpdf (include/MVC/View/views/view.sugarpdf.php)
This new SugarView instance generates the PDF document. As with all SugarViews, ViewSugarpdf can be overridden with by
modules/<myModule>/views/view.sugarpdf.php
The Sugarpdf view can be launched by
module=<mymodule>&action=sugarpdf&sugarpdf=<XXX>
TCPDF (include/tcpdf/tcpdf.php)
The TCPDF class is the original class from the TCPDF library. Modifications have been made to address some bugs that we encountered during our tests with this library.
Sugarpdf (include/Sugarpdf/Sugarpdf.php)
This class extends the TCPDF class. The following methods have been overridden in this class:
•
Header - This method override the regular Header() method to enable the custom image directory in addition to the OOB image directory.
•
SetFont - This method override the regular SetFont() method to enable the custom font directory in addition to the OOB font directory.
•
Cell - Handle HTML entity decode.
•
getNumLines - This method is a fix for a better handling of the count. It handle the line break between words.
Additional methods have been added to this class:
•
predisplay - preprocessing before the display method is called. Is intended to setup general PDF document properties like margin, footer, header, etc.
•
display - performs the actual PDF content generation. This is where the logic to display output to the PDF should be placed.
•
process - calls predisplay and display.
•
writeCellTable – Method to print a table using the Cell print method of TCPDF
•
writeHTMLTable - Method to print a table using the writeHTML print method of TCPDF
Sugarpdf.XXX
Possible Locations :
•
include/Sugarpdf/sugarpdf/sugarpdf.XXX.php
•
modules/module_name/sugarpdf/sugarpdf.XXX.php
•
custom/modules/module_name/sugarpdf/sugarpdf.XXX.php
These classes extend the Sugarpdf class. They define a specific PDF view which is accessible with the following URL parameters:
•
module=module_name
•
action=sugarpdf
•
sugarpdf=XXX
In this class the display method has to be redefined. It is also possible to override other methods like Header().
The process method of this class is a call from ViewSugarpdf.
The most relevant sugarpdf.XXX class is chosen by SugarpdfFactory.
SugarpdfFactory
The ViewSugarpdf class uses SugarpdfFactory to find the most relevant sugarpdf.XXX class which generates the PDF document for a given PDF view and module.
If one is not found, then Sugarpdf is used.
One of the following file will be used in the following order:
1)
custom/modules/my_module/sugarpdf/sugarpdf.XXX.php
2)
modules/my_module/sugarpdf/sugarpdf.XXX.php
3)
custom/include/Sugarpdf/sugarpdf/sugarpdf.XXX.php
4)
include/Sugarpdf/sugarpdf/sugarpdf.XXX.php
5)
include/Sugarpdf/sugarpdf.php
SugarpdfHelper
This file is included by Sugarpdf.php. This php file is a utils file. It contains many functions that can be used to generate PDFs.
For example, to generate HTML code before using the writeHTML() method o TCPDFf
Available functions :
•
wrapTag, wrapTD, wrapTable ,etc. - These functions help to create an HTML code
•
prepare_string - This function prepare a string to be ready for the PDF printing
•
format_number_sugarpdf - This function is a copy of format_number() from currency with a fix for sugarpdf
FontManager
The FontManager class is a stand-alone class that manages all the fonts for TCPDF.
Functionality:
•
List all the available fonts from the OOB font directory and the custom font directory (it can create a well formatted list for select tag)
•
Get the details of each listed font (Type, size, encoding,...) by reading the font php file
•
Add a new font to the custom font directory from a font file and a metric file
•
Delete a font from the custom font directory
The font list build by the font manager with the listFontFiles() or getSelectFontList() is saved in a cached php file cache/Sugarpdf/cachedFontList.php to prevent to parse the fonts folder every time (if the cached file don't already exist). This file is automatically cleared when the delete() or add() methods are used.
When you create a Font loadable module you will have to call the clearCachedFile() method in a post_execute and post_uninstall actions to clear the cache. Like that, the cache will be rebuild with the last infos.
Example of Font loadable module :
manifest.php
<?php
if(!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');
 
$manifest = array(
 
'acceptable_sugar_versions' => array (
'regex_matches' => array (
0 => "5\.5\.*",
),
),
'acceptable_sugar_flavors' => array (
0 => 'PRO',
1 => 'ENT',
),
'name' => 'Font MSung Light',
'description' => 'Font MSung Light (Trad. Chinese) for SugarPDF',
'author' => 'SugarCRM',
'published_date' => '2009-06-17',
'version' => '0.2',
'type' => 'module',
'icon' => '',
'is_uninstallable' => true,
);
global $installdefs;
$installdefs = array(
'id'=> 'Font MSung Light',
'copy' => array(
array('from'=> '<basepath>/new_files/custom/include/tcpdf/fonts/msungstdlight.php',
'to'=> 'custom/include/tcpdf/fonts/msungstdlight.php',
)
),
'pre_execute'=>array(
0 => '<basepath>/actions/pre_actions.php',
),
'pre_uninstall'=>array(
0 => '<basepath>/actions/pre_actions.php',
),
);
?>
pre_actions.php
 
<?php
require_once("include/Sugarpdf/FontManager.php");
$fontManager = new FontManager();
$fontManager->clearCachedFile();
?>
Chain of Events
1.
Call loadSugarpdf method of the SugarpdfFactory - use to determine which sugarpdf.XXX class to load depending of the sugarpdf URL parameter.
2.
Call the process method of the determined sugarpdf.XXX class - this method builds/prints the PDF
3.
Call the output method of the determined sugarpdf.XXX class - this method outputs the PDF to the user
PDF settings (user and system)
sugarpdf_config.php
The first existing file from the following is used for TCPDF class configuration:
1.
custom/include/Sugarpdf/sugarpdf_config.php
2.
include/Sugarpdf/sugarpdf_config.php
The properties set in this file will affect all the generated SugarPDF files.
Check the comments in the file for more details.
The major settings configured in this file are used in the preDisplay method of the Sugarpdf class.
sugarpdf_default.php
include/Sugarpdf/sugarpdf_default.php is used to store the default value of the PDF settings (system and user).
You can overwrite any default value using custom/include/Sugarpdf/sugarpdf_default.php.
For example if you want to set the default right margin to 25 pdf units, create or modify the file custom/include/Sugarpdf/sugarpdf_default.php with this content:
$sugarpdf_default['PDF_MARGIN_LEFT']=25;
Mechanism
sugarpdf_config sets all PDF settings in constant variables.
The values used to set the variables come from different sources in a specific order:
1.
DB
o
Config table for the system settings (category : sugarpdf)
o
User_preferences table for the user settings
2.
Default value from sugarpdf_default.php in custom directory
o
custom/include/Sugarpdf/sugarpdf_default.php
3.
Default value from sugarpdf_default.php in OOB directory
o
include/Sugarpdf/sugarpdf_default.php
If you modify the settings from the user interface (My Account screen, or PDF settings in admin), the new values will be saved in the DB and will override the default value from sugarpdf_default.php .
The Restore button in PDF settings deletes all sugarpdf settings saved in the config table.
The custom directory
Fonts
location : custom/include/tcpdf/fonts/
The font manager parses this directory for available custom font files in addition to the OOB directory.
Logos
location : custom/themes/default/images
All the uploaded logos from PDF settings are copied to this location.
sugarpdf_default.php
location : custom/include/Sugarpdf/sugarpdf_default.php
This file is included after the OOB sugarpdf_default.php file. It can be used to overwrite any default value for the PDF settings.
sugarpdf.XXX.php
location : custom/include/Sugarpdf/sugarpdf/sugarpdf.XXX.php
OR
location : custom/modules/<AnyModule>/sugarpdf/sugarpdf.XXX.php
These files are used to override a sugarpdf.XXX.php class for a specific module or for the whole application.
Adding New PDF Templates
To create a new SugarPDF document, check existing examples in Quotes, Reports, and Projects first.
Steps
(For OOB remove "custom/")
1.
Add the file custom/modules/<myModule>/sugarpdf/sugarpdf.<mySugarpdf>.php
2.
Into the created file :
a)
require include/Sugarpdf/Sugarpdf.php
b)
create the class <Mymodule>Sugarpdf<mySugarpdf> which extend Sugarpdf
c)
Override display() and preDisplay() methods.
3.
Create a button in the UI to access SugarPDF (module=<Mymodule>&action=sugarpdf&sugarpdf=<mySugarpdf>).
<?php
if(!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');
require_once('include/Sugarpdf/Sugarpdf.php');
class <Mymodule>Sugarpdf<mySugarpdf> extends Sugarpdf{
function preDisplay(){
parent::preDisplay();
// ...
}
function display(){
//Create new page
$this->AddPage();
$this->SetFont(PDF_FONT_NAME_MAIN,'',PDF_FONT_SIZE_MAIN);
$this->fileName = "test.pdf";
$this->Ln1();
$this->writeHTML("<p>Bonjour, comment allez vous?</p>");
// ...
}
// ... other method that you would like to override
}
The useful methods to create a SugarPDF document are :
•
Multicell()
•
writeHTML()
•
writeCellTable()
•
writeHTMLTable()
Smarty
You can choose to create a PDF from a Smarty template. You will have to assign variables to the Smarty template, generate the HTML with Smarty and pass it to TCPDF using the WriteHTML() method. The SugarpdfSmarty class is an helper class which support part of these steps.
Warning : HTML and CSS support in writeHTML() is limited. For more details, read the TCPDF documentation
Example in the Contacts module :
•
Add custom/modules/Contacts/sugarpdf/sugarpdf.test.php with this content :
<?php
if(!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');
 
require_once('include/Sugarpdf/sugarpdf/sugarpdf.smarty.php');
 
/**
* This is an helper class to generate PDF using smarty template.
* You have to extend this class, set the templateLocation and assign
* the Smarty variables in the preDisplay method.
* @author bsoufflet
*/
class ContactsSugarpdfTest extends SugarpdfSmarty{
function preDisplay(){
parent::preDisplay();
$this->templateLocation = "custom/modules/Contacts/tpls/test.tpl";
$this->ss->assign("AA",$this->bean->last_name);
$this->ss->assign("BB","2");
$this->ss->assign("CC","3");
$this->ss->assign("DD","4");
}
}
•
Add custom/modules/Contacts/tpls/test.tpl with this content :
<p>This is just an example of html code to demonstrate some supported CSS inline styles.</p>
<div style="font-weight: bold;">{$AA}</div>
<div style="text-decoration: line-through;">{$BB}</div>
<div style="text-decoration: underline line-through;">{$CC}</div>
<div style="color: rgb(0, 128, 64);">{$DD}</div>
<div style="background-color: rgb(255, 0, 0); color: rgb(255, 255, 255);">background color</div>
<div style="font-weight: bold;">bold</div>
<div style="font-size: xx-small;">xx-small</div>
<div style="font-size: small;">small</div>
<div style="font-size: medium;">medium</div>
<div style="font-size: large;">large</div>
<table>
<tr><td>a</td><td>b</td></tr>
<tr><td>c</td><td>d</td></tr>
</table>
•
Generate the PDF file using this URL : module=Contacts&action=sugarpdf&sugarpdf=test
How to Add a New Font (without Font Manager)
If you have a TCPDF font file (.php) (and the .z and .ctg.z files if they are needed):
•
Create the directory custom/include/tcpdf/fonts if it is not created
•
Copy these files into the directory custom/include/tcpdf/fonts
If you have font file (.ttf or .otf):
•
Follow steps 1 to 5 of the [TCPDF Fonts webpage]
•
Create the directory custom/include/tcpdf/fonts if it is not created
•
Copy all the generated files (.php AND .z and .ctg.z if generated) into the directory custom/include/tcpdf/fonts
makefont.php and the utilities use in the TCPDF Fonts webpage can be found in the TCPDF package in fonts/utils. You can download the TCPDF package [here].
How to Add More Configurations to PDF Settings
•
Create custom/modules/Configurator/metadata/SugarpdfSettingsdefs.php
•
Add any settings that you would like to add to the "basic" or "logo" section ("Advanced" section is not available without modifying an OOB file)
Example :
require_once('include/Sugarpdf/sugarpdf_config.php');
$SugarpdfSettings["sugarpdf_pdf_creator"]=array(
"label"=>$mod_strings["PDF_CREATOR"],
"info_label"=>$mod_strings["PDF_CREATOR_INFO"],
"value"=>PDF_CREATOR,
"class"=>"basic",
"type"=>"text",
"required"=>"true"
);
You can also completely ovewrite the SugarpdfSettings array by writing this for example in the custom SugarpdfSettingsdefs.php file:
require_once('include/Sugarpdf/sugarpdf_config.php');
 
$SugarpdfSettings = array(
"sugarpdf_pdf_title"=>array(
"label"=>$mod_strings["PDF_TITLE"],
"info_label"=>$mod_strings["PDF_TITLE_INFO"],
"value"=>PDF_TITLE,
"class"=>"basic",
"type"=>"text",
),
"sugarpdf_pdf_subject"=>array(
"label"=>$mod_strings["PDF_SUBJECT"],
"info_label"=>$mod_strings["PDF_SUBJECT_INFO"],
"value"=>PDF_SUBJECT,
"class"=>"basic",
"type"=>"text",
)
);
In this example, only two fields will be available in PDF settings.
Note : You can view all the available settings in modules/Configurator/metadata/SugarpdfSettingsdefs.php (commented and not commented).
How to Create a Portal API User
If you are using Sugar Professional, and would like to build a custom portal using the Portal API, you will need to create a Portal API User to communicate with the Sugar server.
You can enable the functionality as follows:
1.
Add the following parameter to config_override.php:
$sugar_config['enable_web_services_us er_creation' ]= true
 
2.
Log into Sugar as the administrator and navigate to the Administration Home page.
3.
Click “User Management”.
4.
To register a new user, from the Users tab, select “Create Portal API User”.
You can now pass this user to the Portal API connect calls.
How to Enable Unsupported Email Configurations
To improve performance, the following email settings have been disabled, by default:
•
The use of POP3 protocol for inbound email accounts.
•
The option to select Sendmail for outbound emails.
While you can enable these settings, support from SugarCRM for these features is no longer available. To re-enable these settings, you will need to add a configuration parameter to the config_override.php file with the value set to true.
The following table outlines the parameter key that must be set for the desired result:
Parameter Name
Result
allow_sendmail_outbound
Enables sendmail for outbound emails.
allow_pop_inbound
Enables the POP3 protocol for inbound mail accounts.
 
For example, to enable the POP3 protocol, the config_override.php file would have the following entry set:
$sugar_config[‘allow_pop_inbound’]= true;
 
Table of Contents Previous Next

Copyright 2004-2010 SugarCRM Inc.
Community Edition License

Add Comment

User Contributed Comments

No user comments found.

Add a Comment
E-mail:
Comment:
Have feedback for us? Drop us a line.
Terms & Conditions | Privacy | Trademark Info | Contact Info | FAQs | SugarCRM Inc.© 2004 - 2009 All rights reserved.