Listening to application events - nth-iteration/savvy GitHub Wiki

Understanding events and the life-cycle of cards is very important to writing Savvy apps. There are four events in the Savvy framework:

• Application.LOAD: Fires once only, when the application first loads immediately before the first card is show.
• Card.EXIT: Fires when a card about to be navigated away from (this event allows you to do tidy up, if necessary, before a card is left.
• Card.READY: Fires just before a card is about to be shown. This event allows you to do preparation, if necessary, before a card is shown.
• Card.ENTER: Fires immediately after a card is made visible and the previous card is made invisible.

Individual cards can listen for events that affect only them or JavaScript can listen to event firing anywhere in an application. The syntax uses the familiar JavaScript addEventListener() method and is similar in each case:

this.addEventListener(Card.ENTER, function(event){
  // will fire only when "this" card is entered
});

application.addEventListener(Savvy.ENTER, function(event){
  // will fire every time any card is entered
});

Similarly, events can be unsubscribed from using the usual JavaScript removeEventListener() syntax.

The event object passed to addEventListener() method's is an extension of the JavaScript CustomEvent object and contains a detail object that provides contextual information about the transition:

• detail.to: The card that is being transitioned to.
• detail.from: The card that is being transitioned from.
• detail.transition: The transition object applied to the transition (e.g. Transition.SLIDE_LEFT, etc.).

For example, the following code would listen for Card.ENTER events globally and update a element in the header with the title of the card entered:

application.addEventListener(Card.ENTER, function (event) {
  var title = application.header.getElementById("title");
  title.innerHTML = event.to.title;
});

Additionally, the Savvy event object contains the continue() method described below.

The main purpose of events such as Card.READY and Card.EXIT to enable set-up and tear-down code to run when as cards as being navigated between. For example, to populate a card with a user's account details when the navigate to it. In some cases, this require asynchronous services, for example AJAX calls, and you may want to delay transitioning to the card until the service has returned.

To do so, simply call the preventDefault() method on the Savvy event object:

event.preventDefault();

When the service returns, call the continue() method on the event to continue the transition:

event.continue();

An entire transition can be cancelled and a new one began by calling the applicaiton.goto() method.

The following sample code will make an AJAX request on a Card.READY event. The transition will be paused while the AJAX request takes place asynchronously. If the AJAX request returns successfully, a variable (user) will be populated with the result and the transition will continue. If the AJAX request throws an error, a new transition to a card with the ID of Error will be initiated.

var user = {}; // will be populated by JSON

this.addEventListener(Card.READY, function(event){

  $.ajax({ // get data on this user
    url: "http://www.example.com/rest/api/user",
    success: function(data) {
      user = data;
      event.continue(); // continue with the transition
    },
    error: function() {
      application.goto("Error"); // show the error card
    }
  );

  event.preventDefault(); // pause the transition while we wait for AJAX
});