Sugar Developer Guide Version 5.1

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 data sources. 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.