Using Script and CSS loading plug-ins for easy Sugar integrations

Matthew Marum —  February 1, 2016

Getting 3rd party JavaScript into Sugar

The most common UI integration point between Sugar and external applications is the trusty Sugar Dashlet. This is why we spend so much time talking about Dashlets here on the blog and at our Sugar Developer events throughout the year. However, if you are building something more complicated than an iframe dashlet integration then there is often a requirement to pull 3rd party JavaScript into the page. For example, many integrations are facilitated using JavaScript API client libraries.  Or there is code that a developer is trying to reuse that relies on JavaScript libraries that Sidecar does not already use.

Out of the box, this developer has a couple different options:

Use JSGroupings Extension

Using JSGroupings extension allows you to include additional JavaScript files with the core Sugar application JS that is pulled into the page when the Sugar application is loaded. The drawback is that this JavaScript will get pulled into the page whether or not it is ever used by a user.

Adding script tags to page dynamically

You could add script tags to your Handlebars template or via a Sidecar controller. But this approach adds a bunch of ugly complexity to your code as you have to manage many routine tasks related to loading scripts.

Providing another way!

But Sugar gives us the tools we need to design another way! Below we will explore using the Sidecar plug-in framework to provide an easy way to dynamically load JavaScript and CSS for use with your custom Sidecar components.

Sidecar Plug-in Framework

In Sugar 7, we introduced a plug-in framework that allows you to Mixin additional functionality into your Sidecar component with minimal fuss. If you have created a Sugar Dashlet before then you have already used the Dashlet Sugar 7 plug-in.

Under the Sidecar covers, the plug-in manager uses Underscore extend() to add properties from the plug-in to your component. In the case of the Dashlet plug-in, this adds the necessary APIs that Sugar needs to display and manage your view within Sugar Dashboards.

There are two important facts to keep in mind when working with Sidecar plug-ins.

Sidecar plug-ins are not extensible

You cannot extend a Sidecar Plug-in like you can a standard Sidecar component such as a view, layout, field, etc. So when creating Sidecar plug-ins, we recommend making them as lightweight and granular as possible so you can easily mix, match, and replace plug-in combinations in Sidecar components.

Sidecar plug-ins should be installed using JSGroupings extension

Also, we recommend registering your new custom Sidecar plug-ins using the JSGroupings extension. Below we will provide a couple of examples that shows more details on how this works.

Registering your Sidecar plug-in

Adding a plug-in to Sugar is as easy as calling app.plugins.register(). Lets break down the parameters.

app.plugins.register(name, validTypes, plugin)

Parameter Description
name (String) Plugin name that you want to use
validTypes (String|Array) list of component types this plugin can be applied to.  Limited to view, field, layout, model, and collection as of Sugar 7.6.
plugin (Object) Plug-in object

Plug-ins are registered after the Sugar application has been initialized. When registering a plug-in using JSGroupings extension, you should do so within an app:init event handler. You will see this in both examples below.

To read the full Sidecar plug-in manager documentation, view the doc blocks in sidecar/src/core/plugin-manager.js.

CssLoader Plug-in

Our CssLoader example is quite simple. The Css Loader plug-in is also available over at the Sugar Integration Building Blocks project in Github. It tracks the Stylesheets loaded in the browser and only adds a new link tag to pull in new CSS files as needed.


ScriptLoader Plug-in

The Script Loader plug-in is also available over at the Sugar Integration Building Blocks open source project in Github. This plug-in relies on RequireJS to do most of the dirty work related to loading and managing JavaScript libraries.


Highcharts and Unicorn Buttons Dashlet Example

Now we can create a simple Dashlet that leverages both of our new plug-ins to easily pull in a couple different external libraries dynamically. In the example below, we use Highcharts and Unicorn UI Buttons but you can adapt this example to use whatever JavaScript or CSS libraries that you need.


Easy right? This is what it looks like when it is installed on a Sugar Dashboard.

Screen Shot 2016-01-28 at 11.38.37 AM

Highchart and Unicorn Buttons within a Dashlet



Matthew Marum


Matt is the Director of Developer Advocacy for SugarCRM. Previously he was an Engineer on Sugar 7 and a Solutions Architect for the OEM program. He is also an avid trail runner, Boston Marathon qualifier and a karaoke aficionado.

9 responses to Using Script and CSS loading plug-ins for easy Sugar integrations


    Great post , I love working with Highcharts.js , Matthew could have more examples of reuse graphics D3.js at Sugar ? 🙂


    Awesome stuff Matt thanks so much ! 😀 So excited about this , started rewriting almost everything to leverage this. You can pretty much go beast mode without worrying sidecar will throw a hissy fit and the callback on loadScript() is super handy for many things even if you want the scripts to load in a certain order ~


    Wow! Another piece of the puzzle has been revealed. Great post Matt. I can’t wait to try this out.


    Anyone has more idea how to go about including less? Was thinking could import it with the help of less.js and tweak loadCss() to accept .less also.
    However they docs at don’t really recommend it ~


    By using this tutorial, I’ve done a package for Sugar Enterprise using CssLoader, ScriptLoader and Highcharts. It worked for a long time.
    But now, in Sugar Enterprise, it started to have this error:

    sugar_grp7.min.js?v=IdWzWaWd4Ole7ei5eBCrVA:351 ReferenceError: Highcharts is not defined
    at n.onLoadScript (components_ce8ae81….js:528)
    at Object.execCb (sugar_grp7.min.js?v=IdWzWaWd4Ole7ei5eBCrVA:408)
    at Module.check (sugar_grp7.min.js?v=IdWzWaWd4Ole7ei5eBCrVA:349)
    at Module.enable (sugar_grp7.min.js?v=IdWzWaWd4Ole7ei5eBCrVA:367)
    at Module.init (sugar_grp7.min.js?v=IdWzWaWd4Ole7ei5eBCrVA:347)
    at sugar_grp7.min.js?v=IdWzWaWd4Ole7ei5eBCrVA:393

    All the plugins / packages are installed, and weren’t modified since deployed.
    Using the same highcarts source url, it works in a php test project.
    I even have opened a Case for Sugar:

    There is some tip to why this is happening?


      The problem was in a condition to check “no data” on the dashlets.
      It still show the graphics as long as there is data to render.
      This error happens because in the Sugar Enterprise dashlets container, the page tries to load the Highcharts multiple times.

      Anyway, thanks.