Introduction

Overview

Sugar was originally written on the LAMP stack (Linux, Apache, MySQL and PHP). Since version 1.0, the Sugar development team has added support for every operating system (including Windows, Unix, and Mac OSX) on which the PHP programming language runs for the Microsoft IIS web server and the Microsoft SQL Server, IBM DB2, and Oracle databases. Designed as the most modern web-based CRM platform available today, Sugar 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.

Background

Sugar is available in five editions: the Community Edition, which is freely available for download under the GPLv3 public license, and the Professional, Corporate, Enterprise, and Ultimate editions, which are sold under a commercial subscription agreement. All five editions are developed by the same development team using the same source tree with extra modules available in the Professional, Corporate, Enterprise, and Ultimate editions. Sugar customers using the Professional, Corporate, Enterprise, and Ultimate editions also have access to Sugar Support, Training, and Professional Services offerings. Contributions are accepted from the Sugar Community, but not all contributions are included because 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 Sugar 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. It is easy to modify one of the core files in the distribution; you should always check for 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

The Sugar application code is based on a modular framework with secure entry points into the application (e.g. index.php or soap.php). All modules, core or custom, must exist in the <sugar root>/modules/ folder. Modules represent business entities or objects in Sugar 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.
65_root.png

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
  • custom : Location for upgrade-safe customizations such as custom field definitions, user interface layouts, and business logic hooks
  • data : Key system files, most notably the SugarBean base class which controls the default application logic for all business objects in Sugar
  • examples : Examples of how to extend Sugar, never run from the main app and should be removed from production instances
  • include : Many Sugar utility functions as well as other libraries that Sugar utilizes as part of its operations are located here. Most notable in this directory is the utils.php file that contains the most widely used utility functions.
  • jssource : Non-minified versions of JS files
  • log4php : This has been deprecated as it has been replaced by LoggerManager.
  • metadata : Relationship metadata for all many-to-many data relationships between the business objects
  • ModuleInstall : Code used to support the Sugar Module Loader
  • modules : Contains all modules in the system. Custom modules installed through the Module Loader exist here as well.
  • portal : Customer portal code v1
  • service : Web Services code for SOAP and REST v2 - v4_1
  • soap : Web Services code for SOAP v1; this has been deprecated.
  • themes : Files used to display the various themes
  • upload : 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)
  • XTemplate : Old templating library that is being phased out and replaced by Smarty, but some code still may use it.
  • Zend : Classes used in the framework

Key Concepts

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

Application Concepts

  • Controller : Directs all incoming page requests. This can be overridden in each module to change the default behavior and 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 detail view, edit view, and list view.
  • Views : A set of user interface actions managed by the Controller, the default views in Sugar include the detail view, edit view, and list view.
  • Display strings : Sugar 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. The $GLOBALS[‘app_list_strings’] array contains the system-wide drop-down 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 mentioned above. The name value is stored in the database where the value is displayed in the Sugar User Interface (UI). Sugar enables you to create and edit drop-down lists and their values through the UI in Studio. Use the handy get_select_options_with_id() utility function to help render the <select> input options to work with drop-down lists in edit views. Use the translate() utility function to translate the 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 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. The main parameters for most calls are:
  • module : The module to be accessed as part of the call
  • action : The action within the module
  • record : The record ID
The following is a sample URL for a Sugar call:
http://{sugar_url}/index.php?module=Contacts&action=DetailView&record=d545d1dd-0cb2-d614-3430-45df72473cfb
This URL invokes the detail view 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, and return_id. This group of request parameters is used when a user cancels an action such as creating or editing a record.
Note: As of Sugar 5.1, entry points were consolidated into index.php. Previous versions had other files as entry points into the application.

Module Framework

All modules, out-of-the-box (OOTB) or custom, are placed in the <sugar root>/modules/folder. Modules are created to represent an object (such as Contacts) in Sugar, store the object’s data points in the database, and provide a UI to create, edit, and delete object records.
The Application Framework section previously mentions an example of a typical call for a detail view action within a module. There are five main actions for a module:
  • List View : This Controller action enables the search form and search results for a module. Users can perform actions such as delete, export, update multiple records (mass update), and drill into a specific record to view and edit the details. Users can see this view by default when they click one of the module tabs at the top of the page. Files in each module describe the contents of the list and search view.
  • Detail View : A detail view displays a read-only view of a particular record. Usually, this is accessed via the list view. The detail view displays the details of the object itself and related items (subpanels). 
    Subpanels are miniature list views of items that are related to the parent object. For example, tasks assigned to a project, or contacts for an opportunity will appear in subpanels in the project or opportunity detail view. 
    ./<module>/metadata/detailviewdefs.php defines a module’s detail view layout. ./<module>/metadata/subpaneldefs.php defines the subpanels that are displayed in the module’s detail view page.
  • Edit View : The edit view page is accessed when a user creates a new record or edits details of an existing one. edit view can also be accessed directly from the list view. <module>/metadata/editviewdefs.php defines a module’s edit view page layout.
  • Save : This Controller action is processed when the user clicks Save in the record’s edit view.
  • Delete : This action is processed when the user clicks Delete in the detail view of a record or in the detail view of a record listed in a subpanel.
The following are driven by the UI framework. This framework relies on metadata files in the requested module.
  • ./<module>/metadata/listviewdefs.php describes the layout of the list view.
  • ./<module>/metadata/searchdefs.php describes the search form tabs above the list view.
  • ./<module>/metadata/editviewdefs.php describes the layout of the edit view.
  • ./<module>/metadata/detailviewdefs.phpdescribes the layout of the detail view.
In addition to the action files described above, the following files are located in the ./<module>/ folder:
  • forms.php : This file contains two functions to render specific JavaScript for validation or other actions during edits/saves. By default you can leave these empty and have them return ‘’;
  • Menu.php : This file is responsible for rendering the Shortcuts menu, which was renamed as Actions menu as of Sugar 6.0. In Community Edition, the Actions menu displays below the module tabs and the Last Viewed bar. In Sugar Ultimate, Enterprise, Corporate, and Professional editions, the Actions menu displays on every module tab. By default, you usually add a link to create a new record, and a link to the list view to search.
  • Popup.php : This file acts as a wrapper to the central Popup class located under the utils folder. It is called when a module wants to get a popup list of records from a related module. The central Popup class uses the Popup_picker.html and ./<module>/metadata/popupdefs.php file to render the popup.
  • Popup_picker.html : This is used by the central Popup class to display a module’s pop-ups.
  • 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 metadata structures in the application, most notably the vardefs metadata.
The following image displays the subfolders within a module folder:
module_dir.png
The following sub-folders are located in the ./<module>/ folder:
  • Dashlets : These are drag-and-drop forms displayed on the Sugar Home and Dashboard tabs. Sugar Dashlets display any data (including data from external connectors), and list view and Chart data for the modules. As a developer of a custom module, you can create a Sugar Dashlet for your new module. For each Sugar Dashlet you create, you will place the necessary files in the ./<module>/Dashlets/ folder.
  • language : This folder holds the strings files for the module. By default you will have an en_us.lang.php file containing ALLstrings used by your module. These strings are represented by the $mod_strings variable 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 dynamic loading via the admin panel of new language packs.
  • metadata : Module-specific metadata files have been added to this folder with the addition of more metadata and extensibility into the Sugar platform. Most of the files and folders in this directory can be overridden by a file of the same name in the ./custom/<module>/metadata/ directory. Files and folders in this directory include:
    • additionaldetails.php : The content of the pop-up displayed in the list view
    • detailviewdefs.php : The field layout for the detail view
    • editviewdefs.php : The field layout for the edit view
    • listviewdefs.php : The base column layout displayed on the list view
    • popupdefs.php : The search fields and list columns for a module’s pop-up view
    • quickcreatedefs.php : The layout for the quick create form utilized in multiple areas of the application
    • searchdefs.php : The field layout for the Basic Search and Advanced Search forms on the list view.
    • SearchFields.php : The mapping of definition of unique search fields in the module
    • studio.php : A mapping for Studio to identify files that override the standard metadata files for a module
    • subpaneldefs.php : The layout of the subpanels as they are shown on the detail view of the module
    • subpanels : A folder storing the definitions of the module’s subpanels that will show on other module detail views when an appropriate relationship (one-to-many or many-to-many) exists
  • tpls : The Smarty template files used for various the module header, footer, etc.
  • views : This folder contains files that can override the default Model-View-Controller (MVC) framework view files. View files can perform multiple actions on the Smarty template or outputted HTML, allowing developers to modify and extend the default UIdisplay classes and take full control of the user interface.

User Interface Framework

SugarCRM uses an implementation of the Model-View-Controller (MVC) pattern as 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 is described in a metadata structure.

Extension Framework

The extension framework in Sugar enables you to implement customizations of existing modules or create new modules. You can extend most of the functionality of Sugar through the various extension framework capabilities in an upgrade-safe manner. The Module Builder tool and Studio tool available in the Admin section enable you to make the customizations outlined below. You can then further extend your system by adding upgrade-safe custom code. The areas open to extension are:
  • Modules : Create new modules and add them to Sugar
  • Vardefs : Add custom fields to existing modules with the addition of your custom module
  • Relationships : Create new relationships between your custom module(s) and existing modules
  • Subpanels : Create/add new subpanel definitions to existing modules
  • Strings : Override or add to module and application strings
  • Menus : Override or add to Actions menus
  • Layout Defs : Specify the displayed subpanels and the order in which they are displayed. Create the layout definition for a custom module and add it as a subpanel to the layout definition of an existing module.

Sugar Dashlets

Sugar Dashlets is a framework that provides for Sugar Dashlet containers to be included in the Sugar UI. Sugar Dashlet container objects display and interact with Sugar module data, with external sources such as 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, located on the Sugar Home page, allow for the customization through simple drag-and-drop tools. The Sugar Dashlet Framework allows developers to easily create new Sugar Dashlets that can be installed in Sugar instances through the Module Loader.

Web Services

Sugar provides a Web Services API interface for developers to build integrations with Sugar for reading and writing data. Sugar 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 APIs, built on top of the NuSOAP PHP library, are included in the Sugar Community, Sugar Professional, Sugar Corporate, Sugar Enterprise, and Sugar Ultimate editions. REST (Representational State Transfer) is used for making method calls through HTTPprotocol 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.

Connectors

The Cloud Connector framework enables developers to integrate data from external web services and widgets into their Sugar installation. Data from existing modules such as Accounts, Contacts, and Leads may act as inputs to retrieve external data.
The Connector classes inside of Sugar create a framework for integrating third party systems within Sugar. Currently there are three different base integrations. Documents allows Sugar to upload documents to a third party system, download documents from that system, and in future allow Sugar to setup sharing of those documents (if supported by the third party system). Meetings help Sugar integrate with external conference room systems or other meeting systems, enabling creation and editing of meetings, inviting attendees to the meeting, and including external meeting information in the email invitation. The Feed integration type allows Sugar to pull newsfeed data in from third party sources and display it in the My Activity Stream on the user’s homepage.
For Community Edition, Sugar supports LinkedIn©’s Company Insider widget and InsideView. Use this as an example connector to learn the framework and create your own. Sugar Ultimate, Sugar Enterprise, Sugar Corporate, and Sugar Professional support additional connectors, such as Hoovers© , Zoominfo, Google Docs, Twitter, Facebook, GoToMeeting, LotusLive, and WebEx, and have the ability to merge the data into existing Sugar records.
The main components for the framework are factories, source, and formatter classes.
Factories return appropriate source or formatter instance for a connector. Sources encapsulate the retrieval of data as a single record, or a list, or records of the connectors. Formatters render the display elements of the connectors. For more information, see the expanded section on Connectors .