Events

Overview

The Backbone events module is a lightweight pub-sub pattern that gets mixed into each Backbone class (Model, View, Collection, Router, etc.). This means that you can listen to or dispatch custom named events from any Backbone object.

Backbone events should not be confused with a jQuery events, which are used for working with DOM events in an API. 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 because, among other similarities, both interfaces include an on() function and allow you to attach an event handler. The targets for jQuery events are DOM elements. The target for Backbone events are Backbone objects.

Sidecar classes extend these base Backbone classes. So each Sidecar object (Layouts, Views, Fields, Beans, Contexts, etc.) supports Backbone events.

Existing Backbone Event Catalog

The current catalog of Backbone events is supported and triggered by the Sugar application. For example, we can listen to built-in Backbone router events, such as the route event, that is triggered by Sidecar. Try running the following JavaScript code from your browser's console:

  SUGAR.App.router.on('route', function(arguments) {
    console.log(arguments);
});

As you click through the Sugar application, each time the router is called, you will see routing events appear in your browser console.

Sidecar Events

Global Application Events

Application events are all triggered on the app.events (SUGAR.App.events) object. Below is a list of application events with a description of when you can expect them to fire. However, please note that these events can be triggered in more than one place and some events, such as app:sync:error, can trigger events such as app:logout.

Bean Events

The following table lists bean object events.

Context Events

The context object is used to facilitate communication between different Sidecar components on the page using events. For example, the button:save_button:click event triggers whenever a user clicks the Save button. The record view uses this event to run Save routines without being tightly coupled to a particular Save button. A list of these contextual events is not plausible because the user interface is continuously changing between versions, and there are many more possibilities based on the views and layouts in each version.

Utilizing Events

Application events can be bound to in any custom JavaScript controller or any JavaScript file loaded into Sugar and included on the page (such as via JSGroupings framework). An example below shows how one could add custom JavaScript code to trigger after the application log out.

./custom/include/javascript/myAppLogoutSuccessEvent.js

  (function(app){
    app.events.on('app:logout:success', function(data) {
        //Add Logic Here
        console.log(data);
    });
})(SUGAR.App);

With the custom event JavaScript file written and in place, include it into the system using the JSGroupings extension.

./custom/Extension/application/Ext/JSGroupings/myAppLogoutSuccessEvent.php

  foreach ($js_groupings as $key => $groupings) {
    foreach  ($groupings as $file => $target) {
    	//if the target grouping is found
        if ($target == 'include/javascript/sugar_grp7.min.js') {
            //append the custom JavaScript file
            $js_groupings[$key]['custom/include/javascript/myAppLogoutSuccessEvent.js'] = 'include/javascript/sugar_grp7.min.js';
        }
        break;
    }
}

Once in place, navigate to Admin > Repair > Rebuild JS Grouping Files. After the JSGroupings are rebuilt, clear your browser cache and the custom JavaScript will now trigger after a successful logout.