In our previous “Hello World” dashlet post, we established what a minimal dashlet entailed. In these next post, we’ll be building on those skills to create a more useful dashlet that takes advantage of Sugar 7 List Views. We will be creating a dashlet for Cases that binds to the list’s Collection and sums the number of Cases by their status. So if the Cases list contains 5 records, and 3 of those are in “New” state and 2 are in “Closed” state then we want our dashlet to display “New: 3” and “Closed: 2”. To the code!
Again, using what we learned in the previous post, we’re going to create a folder in custom/clients/base/views/ called “case-count-by-status“. Inside that folder you should create 3 files:
While technically optional, we will also utilize the Language extension in order to provide multilingual support for our example dashlet. This extension file will be located at custom/Extension/application/Ext/Language/en_us.case-count-by-status.php.
Dashlet Metadata (.php file)
Dashlet metadata is going to look almost identical to our previous “Hello World” dashlet. We’re not doing anything too fancy here, so everything should look basically the same.
Dashlet Metadata Filter Options
Currently there are two main dashlet filter keys that you’ll see in the codebase; “module” and “view”. Across of these filter keys, the main thing to remember is that not specifying a filter at all means that your dashlet will be available in all views of all modules. You only need to add filters if you desire to restrict your dashlet to a specific module or view. Let’s look at the filter keys in more detail.
Specifying a filter means your dashlet will be restricted to specified modules and views. Not specifying a filter means your dashlet will be available in all modules and views.
The module filter lets you add an array of modules where your dashlet can appear. If you wanted your dashlet to appear in the list of available dashlets for only the Accounts, Cases, and Contacts modules then your module filter would look like the following.
'filter' => array( 'module' => array( 'Cases', 'Accounts', 'Contacts', ), )
The view filter lets you add an array of views to limit on which views your dashlet can appear. If you wanted your dashlet to appear only on the Record view, your view filter would look like the following.
'filter' => array( 'view' => array( 'record', ), )
Currently, there are two possible values for the view filter. The List View is indicated by using “records”. The Record View is indicated by using “record”.
Dashlet Controller (.js file)
On a List View, this.context points to the BeanCollection. this.context.parent points to a parent model (when it exists, such as on a dashlet preview).
Dashlet Template (.hbs file)
Again, with a Dashlet you are free to format the display any way you like. However, we do recommend leveraging Sugar’s Styleguide so that your dashlet appears like a seamless extension of the Sugar user interface. It is a great reference for you to leverage that allows your dashlets to appear as just another seamless part of the Sugar 7 application.
In this example, we leveraged some dashlet design patterns and CSS pulled directly from the Sugar 7 Styleguide.
The Sugar Styleguide describes how Sugar 7’s CSS works and the design patterns used in common components such as Dashlets. The Styleguide is how you build seamless UI for Sugar 7.x.
As a Sugar Admin, navigate to Styleguide > Core Elements > Dashboards > Dashlets to view the Dashlets style guide. Specifically, we borrowed CSS from the “Summary” dashlet example listed in the Styleguide.
Here is our Handlebars template we put together leveraging this “Summary” pattern.
Language Extension (.php file)
Finally, in the above Handlebars template and in the dashlet metadata file we have defined some display labels that need to be translated into human readable strings. To accomplish this, we have added a language extension for these new labels that we have introduced.
It is a development best practice to use labels for strings so that your user interface can be translated and supported in multiple languages
The “en_us” at the beginning of this filename is significant. It represents the user locale where these strings are used. If you wanted to created translations for other locales, then this value would be different. For example, French language extensions must start with “fr_FR”.
So now we’ve got a working example dashlet that takes advantage of a module’s List View. Remember to run a Quick Repair and Rebuild and then navigate to your Cases module and add the new dashlet. It should look something like what you see below.