Sidecar and Backbone.js
The Sidecar user interface framework is built on a variety of browser side technologies. Being proficient in these underlying technologies is important for any developer writing Sugar 7 user interface code.
Sugar 7.6.x uses Backbone 0.9.10.
If you’ve ever created a Sugar Dashlet or any other user interface component in Sugar 7 then you will familiar with Backbone concepts such as customizing a View or working with a Model. However, many loosely coupled customizations or integrations with Sugar 7 user interface are possible through the use of Backbone Events.
For server side code, recall that you can use Logic Hooks to trap a Module’s save events instead of overriding a module’s SugarBean. The same pattern can be applied where instead of overriding a core file, you can listen to essential events and take action as they occur.
We will explore more below. The code from this example is also available on Sugar Integration Building Blocks project in Github.
The Backbone.Events module is a lightweight pub-sub pattern that gets mixed in to each Backbone class (Model, View, Collection, Router, etc). This means you can listen to or dispatch custom named events from any Backbone object.
Backbone Events should not be confused with jQuery Events which is an API for working with DOM events. Backbone supports an events hash on Views that can be used to attach event handlers to DOM using jQuery. These are not Backbone Events. This can be confusing since both interfaces include an on() function, allow you to attach an event handler, and other similarities.
The target for jQuery events are DOM elements. The target for Backbone Events are Backbone objects.
Sidecar classes all extend these base Backbone classes. So each Sidecar object (Layouts, Views, Fields, Beans, Contexts, etc.) supports Events.
Existing Backbone Event Catalog
All of the existing catalog of Backbone Events are supported and triggered by the Sugar application.
As you click through the Sugar application, each time the router is called you will see routing events appear in your browser console.
Example Sidecar Events
In addition to existing built-in Backbone Events, the Sidecar framework makes use of a variety of unique events. We will show examples of some events that are particularly useful for customization purposes.
Not all Sidecar Events are documented below. If you are interested, explore further by downloading the Sidecar Dev Tools and use the Application Stream to monitor many Sidecar Events as they are triggered.
Application (Global) Events
Application events are all triggered on app.events (SUGAR.App.events) object. For example, if you wanted to see all global application events printed in your browser console then you could use the following code.
This is a very useful application event to know about. This event is triggered after login and the series of initial synchronization operations is completed.
Some events are triggered only on Bean objects.
Validation tasks are run against a Bean prior to saving a Bean object back to server. If validation passed, then this event will pass TRUE to listeners. If validation failed, then this event will pass FALSE to listeners.
The Context object is often used to facilitate communication between different Sidecar components on the page using Events.
This event is triggered whenever a Save button is clicked. The Record View uses this event to run save routines without being tightly coupled to a particular save button.
Adding a new Record View button
Here is a demonstration of how you can use Events as an alternative to overriding Sidecar controllers. This approach is more upgrade and customization friendly than overriding a core application file.
Step 1: Insert Button Metadata
We need to add Button metadata to the existing Accounts view using a Sidecar Extension. This defines the Sidecar Event to be triggered as well as the target object for the event.
Step 2: Add Event handler JS using JSGroupings
Step 3: Quick Repair and Rebuild
Sidecar Event Management
Here are a couple tips.
For global objects, make sure your event listener is attached only once. Make sure you understand the lifecycle of the objects you are working with. Do not guess.
Events get detached from Sidecar created objects. The Context object and any Layouts, Views, Fields that are created by Sidecar are disposed of whenever a new layout is loaded via Sidecar’s built-in controller. This process detaches any listeners attached on these objects. This is why it was not necessary for us to remove the Context listener in the example above.