Class: SC.appCache

Extends SC.Object.

This is a very simple object that makes it easier to use the window.applicationCache in a SproutCore application.

The reason this object exists is that SproutCore applications are excellent candidates for offline access but, it takes more than a little effort to understand the application cache's various possible states and events in order to use it effectively.

You will likely find a use for SC.appCache in two scenarios. The first is you want to ensure that your users are notified each time a new version of your application is deployed in order to ensure they get the latest version. Because of the manner in which the application cache works, a user may launch a previous version from the cache and not see the new version. In this scenario, you would simply check the value of SC.appCache.get('hasNewVersion') at some point in your app's initialization cycle. If hasNewVersion is true, you can then check SC.appCache.get('isNewVersionValid') to determine whether to show a message to the user informing them of the new version and reload the app or to log that the new version failed to upload so you can fix it.

Note, because the application cache takes some time to determine if a new version exists, hasNewVersion may initially be undefined. Therefore, you will likely want to add an observer to the property and continue on with your app. By using an observer, you can also tap into another feature of SC.appCache, which is to lazily check for updates after the app is loaded. Typically, the browser only checks for updates on the initial load of a page, but by setting SC.appCache.set('shouldPoll', true), you can have SC.appCache check for updates in the background at a set interval. Your observer will then fire if hasNewVersion ever changes while the app is in use.

For example,

// A sample application.
MyApp = SC.Application.create({

  // Called when the value of SC.appCache.hasNewVersion changes.
  appCacheHasNewVersionDidChange: function () {
    var hasNewVersion = SC.appCache.get('hasNewVersion'),
      isNewVersionValid = SC.appCache.get('isNewVersionValid');

    if (hasNewVersion) {
      if (isNewVersionValid) {
        // Show a message to the user.
        MyApp.mainPage.get('newVersionAvailablePanel').append();
      } else {
        // There is a new version available, but it failed to load.
        SC.error('Failed to update application cache.');
      }

      // Clean up.
      SC.appCache.removeObserver('hasNewVersion', this, 'appCacheHasNewVersionDidChange');
    } else {
      // Start polling for new versions.  Because the observer is still attached,
      // appCacheHasNewVersionDidChange will be called if a new version ever becomes available.
      SC.appCache.set('shouldPoll', true);
    }

  }

});

// The loading state in our sample application.
MyApp.LoadingState = SC.State.extend({

  enterState: function () {
    var hasNewVersion = SC.appCache.get('hasNewVersion');

    if (SC.none(hasNewVersion)) {
      // The application cache is either caching for the first time , updating or idle.
      // In either case we will observe it.
      SC.appCache.addObserver('hasNewVersion', MyApp, 'appCacheHasNewVersionDidChange');
    } else if (hasNewVersion) {
      // There is already a new version available, use our existing code to handle it.
      MyApp.appCacheHasNewVersionDidChange();
    } else {
      // There is no new version, but it's possible that one will appear.
      // User our existing code to start polling for new versions.
      MyApp.appCacheHasNewVersionDidChange();
      SC.appCache.addObserver('hasNewVersion', MyApp, 'appCacheHasNewVersionDidChange');
    }
  }

});

The second scenario is if you want to present a UI indicating when the app is ready for offline use. Remember that it takes some time for the browser to retrieve all the resources in the manifest, so an app may be running for a while before it is ready for offline use. In this scenario, you would observe the isReadyForOffline property of SC.appCache.

Like hasNewVersion, isReadyForOffline has three possible values: undefined, true or false, where the property is undefined while the value is still undetermined.

For example,

// A sample view.
MyApp.MyView = SC.View.extend({

  childView: ['offlineIndicatorCV'],

  // An image we use to indicate when the app is safe to use offline.
  offlineIndicatorCV: SC.ImageView.extend({
    valueBinding: SC.Binding.oneWay('SC.appCache.isReadyForOffline').
      transform(function (isReadyForOffline) {
        if (isReadyForOffline) {
          return 'offline-ready';
        } else if (SC.none(isReadyForOffline)) {
          return 'offline-unknown';
        } else {
          return 'offline-not-ready';
        }
      })
  })

});

The following are some excellent resources on the application cache that were used to develop this class:

• Using the application cache - HTML | MDN
• Appcache Facts
• Offline Web Applications - Dive Into HTML5

Defined in: app_cache.js

Since:

Version 1.10

Field Summary