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.
Highchart and Unicorn Buttons within a Dashlet
