Sugar Developer Guide Version 5.1

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 6 files that define this Sugar Dashlet

1.	JotPadDashlet.php – JotPad Class

2.	JotPadDashlet.meta.php – meta data 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 via 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’ve created your Sugar Dashlet.

This will rebuild the cache file /<cache dir>/Dashlets/Dashlets.php by scanning the folders /modules/ and /custom/modules/ for Dashlet Files.