Sugar Community Edition Documentation

Sugar Community Edition 5.5 Documentation

Sugar Developer Guide

Version 5.5.0

Chapter 1 SugarCRM Overview

SugarCRM was originally written on the LAMP stack (Linux, Apache, MySQL and PHP). Since version 1.0, the SugarCRM development team has added support for every operating system that the PHP programming language runs on (including Windows, Unix and Mac OSX), for the Microsoft IIS Web server and for the Microsoft SQL Server and Oracle databases. Designed as the most modern Web-based CRM platform available today, SugarCRM has quickly become the business application standard for companies around the world. See the Supported Platforms page for detailed information on supported software versions and recommended stacks.

SugarCRM is available in three editions: the Community Edition, which is freely available for download under the GPLv3 public license, and the Professional and Enterprise Editions, which are sold under a commercial subscription agreement. All three editions are developed by the same development team using the same source tree with extra modules available in the Professional and Enterprise Editions. Sugar customers using the Professional and Enterprise Editions also have access to Sugar Support, Training and Professional Services offerings. Contributions are happily accepted from the Sugar Community, but not all contributions are included as SugarCRM maintains high standards for code quality.

From the very beginning of the SugarCRM Open Source project in 2004, the SugarCRM development team designed the application source code to be examined and modified by developers. The SugarCRM application framework has a very sophisticated extension model built into it allowing developers to make significant customizations to the application in an upgrade-safe and modular manner. While it may be easy to modify one of the core files in the distribution, you should always check to see first if there is an upgrade-safe way to make your changes. Educating developers on how to make upgrade-safe customizations is one of the key goals of this Developer Guide.

Application Framework Overview

The SugarCRM application code is based on a modular framework with secure entry points into the application (e.g. index.php or soap.php). All modules, whether core modules or ones you create and install through the Module Loader, must exist in the <sugar root>/modules/ folder. Typically modules represent business entities or objects in SugarCRM, such as ‘Contacts’, and the object has fields or attributes that are stored in the database, as well as a user interface (UI) for the user to create and modify records. A module encompasses definitions for the data schema, user interface and application functionality.

The structure of Sugar’s root directory is shown below.

Directory Structure

SugarCRM code resides in various directories within the Sugar installation. The structure of the directories within the Sugar application consists of the following root level directories:

•

cache: Various cache files written to the file system to minimize database accesses and store user interface templates created from metadata. Also files uploaded into the application such as Note Attachments or Documents reside in this directory (refer to ‘upload_dir’ parameter in the config.php file) which means that this is an active cache directory and not all files can be deleted from this directory.

•	custom: Stores upgrade-safe customizations such as custom field definitions, user interface layouts and business logic hooks.

•	data: Key system files are located here, most notably the SugarBean base class which controls the default application logic for all business objects in Sugar.

•	include: Many Sugar utility functions are located here as well as other libraries that Sugar utilizes as part of its operations. Most notably in this directory is the utils.php file that contains all of the most widely used utility functions.

•	metadata: This file contains relationship metadata for all many-to-many data relationships between the business objects.

•	modules: This folder contains all modules in the system. Custom modules installed through the Module Loader exist here as well.

Key Concepts

These are the main files, classes and application concepts that comprise the Sugar platform.

Application Concepts

•	Controller: Directs all incoming page requests. It can be overridden in each module to change the default behavior. It relies on Entry point parameters - described below - to serve the appropriate page.

•	Views: A set of user interface actions managed by the Controller, the default views in Sugar include the DetailView, EditView and ListView.

•

Display Strings: SugarCRM is fully internationalized and localizable. Every language pack has its own set of display strings which is the basis of language localization. There are two types of display strings in the Sugar application: application strings and module strings. Application strings contain the user interface labels displayed globally throughout the application. The $GLOBALS[‘app_strings’] array contains these labels. There is also the $GLOBALS[‘app_list_strings’] array which contains the system-wide dropdown list values. Each language has its own application strings variables. The $GLOBALS[‘mod_strings’] array contains strings specific to the current, or in-focus, module..

•

Dropdown Lists: Dropdown lists are represented as ‘name’ => ‘value’ array pairs located in the application strings as mentioned above. The ‘name’ value is stored in the database where the ‘value’ is displayed to the user in the UI. You are able to create and edit dropdowns and their values via the UI in the admin Studio tool. For working with dropdown lists in EditViews use the handy get_select_options_with_id() utility function to help render the <select> input options. Also use the handy translate() utility function for translating whatever string key you are working with into the user’s currently selected display language.

Files

•

SugarBean.php: This file located under the ‘<sugar root>/data’ folder contains the SugarBean base class used by all business entity or module objects. Any module that reads, writes or displays data will extend this class. The SugarBean performs all of the heavy lifting for data interactions, relationship handling, etc.

•	modules.php: The modules.php file is a critical file in Sugar. It contains several variables that define which modules are active and usable in the application.

Variables

•	$dictionary: The $dictionary array contains all module field variable definitions (vardefs), as well as the relationship metadata for all tables in the database. This array is dynamically built based upon the vardefs.php definitions.

Entry Points

The primary user interface entry point for Sugar is through index.php located in the root Sugar folder. There are three main parameters for most calls within Sugar, they are:

•	module: The module to be accessed as part of the call

•	action: The action to be taken by the application within the module

•	record: The record id to be accessed

An example URL for a Sugar call might be:

http://www.yoursugarsite.com/index.php?module=Contacts&action=DetailView&record=d545d1dd-0cb2-d614-3430-45df72473cfb

This URL invokes the DetailView action from within the Contacts module to display the record denoted by the record request value.

Other commonly used parameters are ‘return_module’, ‘return_action’, return_id’. This group of request parameters are typically used when a user selects to cancel out of an action such as when creating/editing a record.

Note: For version 5.1 most entry points were consolidated into index.php. Previous versions had other files as entry points into the application.

Module Framework Overview

All modules, whether core modules or ones you create and install through the Module Loader are placed in the <sugar root>/modules/ folder. Typically modules are created when you have to represent an object in Sugar, such as ‘Contacts’, and the object has data points that need to be stored in the database, as well as have an UI for the user to create, edit, and delete records for the object.

Let us look at a modules framework and how it fits into the overall Sugar Platform.

In the Platform Overview section, we show an example of a call that would be typical for a DetailView action within a particular module. There are five main actions for a module:

•

ListView: This Controller action exists to provide the user with the search form and search results for a module. From this screen, a user can take such actions as deleting, exporting, and mass updating multiple records or drill into a specific record to view and edit the details. The user is dropped into this view by default when he clicks on one of the tabs at the top of the application. Files in each module describe the contents of the list and search view.

•

DetailView: A DetailView provides a read-only detail view of a particular object. Typically, a user will access a record’s DetailView via a ListView. The user can view the details of the object itself and, below the details, will see lists of related items that are referred to as ‘SubPanels’ in Sugar. SubPanels act as mini-ListViews of items that are related to the parent object accessed with the DetailView action. For instance, Tasks assigned to a Project or Contacts to an Opportunity will appear in SubPanels below the Project or Opportunity. <module>/metadata/detailviewdefs.php defines a module's DetailView page's layout. <module>/metadata/subpaneldefs.php defines the subpanels that are visible under the module's DetailView page.

•	EditView: The EditView action is accessed whenever a user is creating a new record or editing details of an existing one. It is possible to directly access the EditView from the ListView. <module>/metadata/editviewdefs.php defines a module's EdtiView page's layout.

•	Save: This Controller action is processed whenever the user clicks the ‘Save’ button from the EditView of a record.

•	Delete: This action is processed whenever the user clicks the ‘Delete’ button from the DetailView of a record or, as a special case, from an item listed in a SubPanel.

These actions are driven by the UI framework, and the framework relies on metadata files in the requested module.

•	<module>/metadata/listviewdefs.php describes the layout of the ListView.

•	<module>/metadata/searchdefs.php describes the search form tabs above the ListView.

•	<module>/metadata/editviewdefs.php describes the layout of the EditView.

•	<module>/metadata/detailviewdefs.php describes the layout of the DetailView.

Besides the action files described above you probably have noticed some additional files located in the folder.

•	forms.php: This file contains two functions to render specific JavaScript for validation or other actions you might want to perform during edits/saves. By default you can leave these empty and have them return ‘’;

•	Menu.php: This file is responsible for the rendering of shortcuts menu you typically see on the left hand side of the screen. By default you usually add a link to create a new record, and a link to the ListView to search.

•

Popup.php: This file acts as a wrapper to the central Popup class located under the utils folder. It is called if ever another module wants to get a popup list of records from a related module. The central Popup class then uses the Popup_picker.html and <MODULE_NAME>/metadata/popupdefs.php file to render the popup.

•	Popup_picker.html: Used by the central Popup class to display a module’s popup.

•	vardefs.php: The vardefs.php metadata file defines db and non-db fields for Sugar objects as well as relationships between objects.

•	field_arrays.php: This file is deprecated as of Sugar version 5.1. It has been phased out over time with the addition of additional metadata structures in the application, most notably the vardefs metadata.

Now let us look at the various subfolders within a module folder to complete the overview of the module structure.

•

Sugar Dashlets: Sugar Dashlets are drag-and-drop forms displayed on the Sugar Home and Dashboard tabs. These forms can display any data, including data pulled from external connectors. With the Sugar default application, they contain ListView and Chart data for the application modules. As a developer of a custom module you are able to create a Sugar Dashlet view to your new module. For each Sugar Dashlet you create, you will place the necessary files in the ‘<MODULE_NAME>/Dashlets’ folder.

•

language: The language folder’s main purpose is to hold the strings files for the your module. By default you will have an en_us.lang.php file which contains ALL strings used specifically by your module. These strings are represented by the $mod_strings variable which can be accessed at any time after a global $mod_string call. The .html files located in this folder are used by the Help subsystem. Sugar provides the capabilities for multi-language support and the dynamic loading via the admin panel of new language packs.

•

metadata: As more and more metadata and extensibility has been built into the Sugar Platform, module-specific metadata files have been added to this folder. Some of the most important files in this directory include: additionaldetails.php defines the content of the popup displayed in the ListViews; listviewdefs.php defines the columns displayed in the module ListView page; popupdefs.php defines the search fields and list columns for a module’s popup; SearchFields.php defines the Basic Search and Advanced Search forms seen in the ListView page; studio.php defines how the Studio tool interacts with a module's metadata files.

•

subpanels: This folder will hold the definitions of a module’s subpanels when that module is related in a one-to-many or many-to-many fashion. Typically you have the default.php file. You can add any number of versions here. Alternatively, you can also create custom versions of SubPanels of other modules to be displayed by your custom module. For example, with your custom module you could make relate it with the Contacts module and have a Contacts subpanel under your DetailView. For instance, you could build and place a ‘ForWidgets.php’ file under the ‘<sugar root>/modules/Contacts/subpanels/’ folder. The file name is referenced by the ‘subpanel_name’ parameter called from a ‘layout_defs.php’ definition.

•	tpls: This folder holds Smarty template files. Currently the only specific use of this is for the Quick Create forms.

•

views: In this folder are files that can override the default Model-View-Controller (MVC) framework view files. View files can perform multiple different actions on the Smarty template or outputted HTML, allowing developers to modify and extend the default UI display classes and take full control of the user interface.

User Interface Framework Overview

SugarCRM uses an implementation of the Model-View-Controller (MVC) pattern the base of all application interactions. Working closely with the MVC framework is a metadata-driven UI framework where the high-level specification of parts of the user interface in the application is described in a metadata structure.

Extension Framework Overview

The extension framework in Sugar allows you to implement customizations of existing modules or create entirely new modules. Through the various extension framework capabilities you can extend most of the functionality of Sugar in an upgrade-safe manner. The Module Builder tool and Studio tool available in the Admin screen allows you to make the most common customizations outlined below. You can then further extend your system by adding upgrade-safe custom code. The areas open to extension are:

•	Modules: You are to create entirely new modules and add them to Sugar.

•	Vardefs: You are able to add custom fields to existing modules with the addition of your custom module.

•	Relationships: New relationships can be added to the system between your new modules and existing modules in Sugar.

•	SubPanels: With the addition of new relationships you can create/add new SubPanel definitions to existing modules.

•	Strings: Module and application strings can be added or overridden.

•	Menus: Shortcut menus can be added to or overridden

•	Layout Defs: Which subpanels are displayed, and in which order they are displayed can be altered. Not only can you create the layout_def for you newly added module, but you can also edit the layout_def of an existing module to add your new module as a subpanel.

Sugar Dashlets Overview

Sugar Dashlets is a framework that provides for Sugar Dashlet containers to be included in the Sugar UI. Sugar Dashlet container objects can display and interact with Sugar module data, with external sources like RSS feeds and with web services like Google Maps. Released originally in Sugar 4.5, Sugar Dashlets are a powerful new way to combine highly functional mash-ups in an attractive and easily tailored AJAX-based UI framework. Sugar Dashlets are located on the home page and Dashboard page and allow for the customization via simple drag-and-drop tools. The Sugar Dashlet Framework allows developers to easily create new Sugar Dashlets that are installable into SugarCRM instances via the Module Loader.

Web Services Overview

SugarCRM provides a Web Services API interface for developers to build integrations with SugarCRM for reading and writing data. SugarCRM provides Web Services APIs through the NuSOAP PHP implementation of the SOAP and REST protocol. SOAP (Simple Object Access Protocol) is used for making Remote Procedure Calls through the HTTP protocol by relaying messages in XML. The SugarSoap API’s, built on top of the NuSOAP PHP library, are included in the Sugar Community, Sugar Professional and Sugar Enterprise editions. REST (Representational State Transfer) is used for making method calls through HTTP protocol by sending and receiving messages in JSON/Serialize format. Framework supports the addition of multiple formats for REST. For example, you can add XML format to send and receive data.

Cloud Connectors Overview

The Cloud Connector framework enables developers to integrate data from external Web Services and widgets into their SugarCRM installation. Data from existing modules such as accounts, contacts, and leads may act as inputs to retrieve external data.

For Community Edition, Sugar supports LinkedIn©’s Company Insider widget. You can use this as an example connector to learn the framework and create your own. Sugar Professional and Sugar Enterprise also support additional connectors, such as Hoovers© and Jigsaw©) and have the ability to merge the data into existing Sugar records.

The main components for the framework are the factories, source and formatter classes.

The factories are responsible for returning the appropriate source or formatter instance for a connector. Sources are responsible for encapsulating the retrieval of data as a single record, or a list, or records of the connectors. Formatters are responsible for rendering the display elements of the connectors. For more information, see Chapter 4, Customizing Sugar.