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:

Defined in: app_cache.js

Since:
Version 1.10

Field Summary

Field Detail

Read Only
hasNewVersion Boolean

Whether there is a new version of the application's cache or not.

This property is undefined until it can be determined that a new version exists or not. Note that the new version may not necessarily be valid. You should check isNewVersionValid after determining that hasNewVersion is true.

Default value:
undefined
interval Number
The interval in milliseconds to poll for updates when shouldPoll is true.
Default value:
1800000 (30 minutes)
Read Only
isNewVersionValid Boolean

Whether the new version is valid or not.

This property is undefined until it can be determined that a new version exists or doesn't exist and if it does exist, whether it is valid or not.

Default value:
undefined
Read Only
isReadyForOffline Boolean

Whether the application may be run offline or not.

This property is undefined until it can be determined that the application has been cached or not cached.

Default value:
undefined
progress Number
The progress of the application cache between 0.0 (0%) and 1.0 (100%).
Default value:
0.0
shouldPoll Boolean

Whether or not to regularly check for updates to the application cache while the application is running.

This is useful for applications that are left open for several hours at a time, such as a SproutCore application being used in business. In order to ensure that the users have the latest version, you can set this property to true to have the application regularly check for updates.

Updates are run using the background task queue, so as to pose the smallest detriment possible to performance.

Default value:
false
status Number

The current window.applicationCache status.

This is a KVO mapping of window.applicationCache.status. Possible values are: window.applicationCache.UNCACHED window.applicationCache.IDLE window.applicationCache.CHECKING window.applicationCache.DOWNLOADING window.applicationCache.UPDATEREADY window.applicationCache.OBSOLETE

Because of the various interpretations these statuses can mean, you will likely find it easier to use the helper properties on SC.appCache instead.

Default value:
0
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)