Sugar Dashlets
Dashlets use the abstract factory design pattern. Individual dashlets extend the base abstract class Dashlet.php, list view Dashlets extend the base abstract class DashletGeneric.php, and chart dashlets extend the base abstract class DashletGenericChart.php.
Sugar Dashlet instances must be stored in one of the following directories:
- ./modules/<module>/Dashlets/
- ./custom/modules/<module>/Dashlets/
Sugar Dashlet developers use the ./custom/ directory to ensure their Sugar Dashlets are not manipulated by upgrades. Sugar Dashlets offered in base Sugar releases are located in the standard ./modules/ directory.
Sugar Dashlet Files
The file name containing the main Sugar Dashlet code must match the Sugar Dashlet’s class name. For example, the Sugar Dashlet class JotPadDashlet is located in the file ./modules/Home/Dashlets/JotPadDashlet/JotPadDashlet.php. The JotPadDashlet is a sample Sugar Dashlet released originally in Sugar 4.5. It serves as a useful example from which to begin your development efforts.
A metadata file accompanies each Sugar Dashlet. It contains descriptive information about the Sugar Dashlet defined below:
$DashletMeta['JotPadDashlet'] = array (
'title' => 'LBL_TITLE',
'description' => 'LBL_TITLE',
'icon' => 'themes/Sugar/images/Accounts.gif',
'category' => 'Tools',
);
The naming convention for the metadata file is className.meta.php, where className is the name of the Sugar Dashlet. The metadata file must reside in the same directory as the Sugar Dashlet code. For JotPad Dashlet, the meta file is stored in ./modules/Home/Dashlets/JotPadDashlet/JotPadDashlet.meta.php.
The ‘title’ and ‘description’ elements are translated. If the values here match a key in the array $DashletStrings (from the language file) then they will be translated, otherwise it will display the literal string. (It is a best practice to use translatable language strings so that your Sugar Dashlet is international!)
Language files have a similar naming convention: className.locale.lang.php (for example ./modules/Home/Dashlets/JotPadDashlet/JotpadDashlet.en_us.lang.php )
Icon files can either be defined in the .metadata file or included in the Sugar Dashlet Directory (for example ./modules/Home/Dashlets/JotPadDashlet/JotPadDashlet.icon.png).
Sugar scans for image files in the corresponding Sugar Dashlet directory.
Templating
The suggested templating engine for Sugar Dashlets is Smarty. This is not a requirement.
Categories
There are five categories for Sugar Dashlets:
- Module Views : Generic views of data in modules
- Portal : Sugar Dashlets that allow access to outside data (RSS, Web services, etc)
- Charts : Data charts
- Tools : Various tools such as notepad, calculator, or world clock
- Miscellaneous : Any other Sugar Dashlet
Sugar Dashlet base class
The main Sugar Dashlet base class is ./include/Dashlets/Dashlet.php and all Sugar Dashlets should extend this class.
Assign a unique ID to each Sugar Dashlet. This ID is used in the displayed HTML document and enable multiple Sugar dashlets of the same type to be included on the page.
Sugar Dashlets are stored in the table user_preferences under the Dashlet’s name and home category.
The options element stores the options for the Sugar dashlet. This element is loaded/stored by storeOptions/loadOptions functions in the base Dashlet class.
Sugar Dashlets JavaScript
Sugar Dashlet utility functions are located in ./include/JavaScript/Dashlets.js and contains the following:
postForm: function(theForm, callback) {}
postForm is used to post the configuration form through AJAX.
The callback to remove the configuration dialog is SUGAR.sugarHome.uncoverPage:
callMethod: function(DashletId, methodName, postData, refreshAfter, callback) {}
callMethod is a generic way to call a method in a Dashlet class. Use this function to generically call a method within your Dashlet class (php side). Refresh your Dashlet after a call and utilize a callback function (optional). This method can also be used to proxy AJAXcalls to Web services that do not exist in the Sugar installation, for example, Google Maps Mash-up.
