concord-consortium/codap — pull request #11 by rklancer (2014-10-02 20:23:59+00:00)
Title: Save and restore cross-domain interactives via postMessage

@bfinzer @jsandoe ndoe take a look at this approach. The following modifications were made:

In initGame:

1. `DG.doCommand` and the underlying implementation at `DG.GameController.dispatchCommand` now accept optional callbacks. When the callback is passed, the command result is passed as the argument of the callback. This allows the command to complete in a different event loop than the one in which it was invoked.
2. When a cross-domain interactive invokes `doCommand` via iframePhone, it uses the callback form
3. The `initGame` handler now takes a callback.
4. In `handleInitGame`, if iframePhone was previously used by the interactive (for example to invoke `initGame`), and `doAppCommandFunc` is not found, CODAP passes the game its initial state by invoking `DG.codapPhone.call`, and waits for the game's response before completing `initGame` and calling the command-completion callback

in exportDocument/saveDocument:

1. `DG.AppController.exportDocument` and `DG.DocumentController.saveDocument` use a callback form of `DG.DocumentController.exportDocument`. It appears that no code depends on the return value or immediate availability of the side effect of these 2 methods, so they do not take callbacks themselves.
2. `DG.DocumentController.exportDocument` uses a callback form of `DG.DocumentArchiver.saveDocument`
3. `DG.DocumentArchiver.saveDocument` uses a callback form of `DG.gameSelectionController.saveCurrentGameState` (`saveDocument` relies on a side effect of `saveCurrentGameState`, so it needs to defer until the game state is saved)
4. If `DG.doCommand` has been invoked via iframePhone, and `doAppCommandFunc` is not defined, then `DG.gameSelectionController.saveCurrentGameState` invokes `DG.gamePhone.call` to get the data to be saved. Either way, it invokes its completion callback when it has the data.

You can see how CartWeight implements the `doAppCommand` here: https://github.com/concord-consortium/codap-data-interactives/blob/4c5630dee2bb6952cf53c2a52f5ec957a3b8c87d/CartWeight/js/cart_game.js#L29-L44