diff options
Diffstat (limited to 'includes/js/dojox/off/sync.js')
| -rw-r--r-- | includes/js/dojox/off/sync.js | 690 |
1 files changed, 690 insertions, 0 deletions
diff --git a/includes/js/dojox/off/sync.js b/includes/js/dojox/off/sync.js new file mode 100644 index 0000000..9927fbe --- /dev/null +++ b/includes/js/dojox/off/sync.js @@ -0,0 +1,690 @@ +if(!dojo._hasResource["dojox.off.sync"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code. +dojo._hasResource["dojox.off.sync"] = true; +dojo.provide("dojox.off.sync"); + +dojo.require("dojox.storage.GearsStorageProvider"); +dojo.require("dojox.off._common"); +dojo.require("dojox.off.files"); + +// Author: Brad Neuberg, bkn3@columbia.edu, http://codinginparadise.org + +// summary: +// Exposes syncing functionality to offline applications +dojo.mixin(dojox.off.sync, { + // isSyncing: boolean + // Whether we are in the middle of a syncing session. + isSyncing: false, + + // cancelled: boolean + // Whether we were cancelled during our last sync request or not. If + // we are cancelled, then successful will be false. + cancelled: false, + + // successful: boolean + // Whether the last sync was successful or not. If false, an error + // occurred. + successful: true, + + // details: String[] + // Details on the sync. If the sync was successful, this will carry + // any conflict or merging messages that might be available; if the + // sync was unsuccessful, this will have an error message. For both + // of these, this should be an array of Strings, where each string + // carries details on the sync. + // Example: + // dojox.off.sync.details = ["The document 'foobar' had conflicts - yours one", + // "The document 'hello world' was automatically merged"]; + details: [], + + // error: boolean + // Whether an error occurred during the syncing process. + error: false, + + // actions: dojox.off.sync.ActionLog + // Our ActionLog that we store offline actions into for later + // replaying when we go online + actions: null, + + // autoSync: boolean + // For advanced usage; most developers can ignore this. + // Whether we do automatically sync on page load or when we go online. + // If true we do, if false syncing must be manually initiated. + // Defaults to true. + autoSync: true, + + // summary: + // An event handler that is called during the syncing process with + // the state of syncing. It is important that you connect to this + // method and respond to certain sync events, especially the + // "download" event. + // description: + // This event handler is called during the syncing process. You can + // do a dojo.connect to receive sync feedback: + // + // dojo.connect(dojox.off.sync, "onSync", someFunc); + // + // You will receive one argument, which is the type of the event + // and which can have the following values. + // + // The most common two types that you need to care about are "download" + // and "finished", especially if you are using the default + // Dojo Offline UI widget that does the hard work of informing + // the user through the UI about what is occuring during syncing. + // + // If you receive the "download" event, you should make a network call + // to retrieve and store your data somehow for offline access. The + // "finished" event indicates that syncing is done. An example: + // + // dojo.connect(dojox.off.sync, "onSync", function(type){ + // if(type == "download"){ + // // make a network call to download some data + // // for use offline + // dojo.xhrGet({ + // url: "downloadData.php", + // handleAs: "javascript", + // error: function(err){ + // dojox.off.sync.finishedDownloading(false, "Can't download data"); + // }, + // load: function(data){ + // // store our data + // dojox.storage.put("myData", data); + // + // // indicate we are finished downloading + // dojox.off.sync.finishedDownloading(true); + // } + // }); + // }else if(type == "finished"){ + // // update UI somehow to indicate we are finished, + // // such as using the download data to change the + // // available data + // } + // }) + // + // Here is the full list of event types if you want to do deep + // customization, such as updating your UI to display the progress + // of syncing (note that the default Dojo Offline UI widget does + // this for you if you choose to pull that in). Most of these + // are only appropriate for advanced usage and can be safely + // ignored: + // + // * "start" + // syncing has started + // * "refreshFiles" + // syncing will begin refreshing + // our offline file cache + // * "upload" + // syncing will begin uploading + // any local data changes we have on the client. + // This event is fired before we fire + // the dojox.off.sync.actions.onReplay event for + // each action to replay; use it to completely + // over-ride the replaying behavior and prevent + // it entirely, perhaps rolling your own sync + // protocol if needed. + // * "download" + // syncing will begin downloading any new data that is + // needed into persistent storage. Applications are required to + // implement this themselves, storing the required data into + // persistent local storage using Dojo Storage. + // * "finished" + // syncing is finished; this + // will be called whether an error ocurred or not; check + // dojox.off.sync.successful and dojox.off.sync.error for sync details + // * "cancel" + // Fired when canceling has been initiated; canceling will be + // attempted, followed by the sync event "finished". + onSync: function(/* String */ type){}, + + synchronize: function(){ /* void */ + // summary: Starts synchronizing + + //dojo.debug("synchronize"); + if(this.isSyncing || dojox.off.goingOnline || (!dojox.off.isOnline)){ + return; + } + + this.isSyncing = true; + this.successful = false; + this.details = []; + this.cancelled = false; + + this.start(); + }, + + cancel: function(){ /* void */ + // summary: + // Attempts to cancel this sync session + + if(!this.isSyncing){ return; } + + this.cancelled = true; + if(dojox.off.files.refreshing){ + dojox.off.files.abortRefresh(); + } + + this.onSync("cancel"); + }, + + finishedDownloading: function(successful /* boolean? */, + errorMessage /* String? */){ + // summary: + // Applications call this method from their + // after getting a "download" event in + // dojox.off.sync.onSync to signal that + // they are finished downloading any data + // that should be available offline + // successful: boolean? + // Whether our downloading was successful or not. + // If not present, defaults to true. + // errorMessage: String? + // If unsuccessful, a message explaining why + if(typeof successful == "undefined"){ + successful = true; + } + + if(!successful){ + this.successful = false; + this.details.push(errorMessage); + this.error = true; + } + + this.finished(); + }, + + start: function(){ /* void */ + // summary: + // For advanced usage; most developers can ignore this. + // Called at the start of the syncing process. Advanced + // developers can over-ride this method to use their + // own sync mechanism to start syncing. + + if(this.cancelled){ + this.finished(); + return; + } + this.onSync("start"); + this.refreshFiles(); + }, + + refreshFiles: function(){ /* void */ + // summary: + // For advanced usage; most developers can ignore this. + // Called when we are going to refresh our list + // of offline files during syncing. Advanced developers + // can over-ride this method to do some advanced magic related to + // refreshing files. + + //dojo.debug("refreshFiles"); + if(this.cancelled){ + this.finished(); + return; + } + + this.onSync("refreshFiles"); + + dojox.off.files.refresh(dojo.hitch(this, function(error, errorMessages){ + if(error){ + this.error = true; + this.successful = false; + for(var i = 0; i < errorMessages.length; i++){ + this.details.push(errorMessages[i]); + } + + // even if we get an error while syncing files, + // keep syncing so we can upload and download + // data + } + + this.upload(); + })); + }, + + upload: function(){ /* void */ + // summary: + // For advanced usage; most developers can ignore this. + // Called when syncing wants to upload data. Advanced + // developers can over-ride this method to completely + // throw away the Action Log and replaying system + // and roll their own advanced sync mechanism if needed. + + if(this.cancelled){ + this.finished(); + return; + } + + this.onSync("upload"); + + // when we are done uploading start downloading + dojo.connect(this.actions, "onReplayFinished", this, this.download); + + // replay the actions log + this.actions.replay(); + }, + + download: function(){ /* void */ + // summary: + // For advanced usage; most developers can ignore this. + // Called when syncing wants to download data. Advanced + // developers can over-ride this method to use their + // own sync mechanism. + + if(this.cancelled){ + this.finished(); + return; + } + + // apps should respond to the "download" + // event to download their data; when done + // they must call dojox.off.sync.finishedDownloading() + this.onSync("download"); + }, + + finished: function(){ /* void */ + // summary: + // For advanced usage; most developers can ignore this. + // Called when syncing is finished. Advanced + // developers can over-ride this method to clean + // up after finishing their own sync + // mechanism they might have rolled. + this.isSyncing = false; + + this.successful = (!this.cancelled && !this.error); + + this.onSync("finished"); + }, + + _save: function(callback){ + this.actions._save(function(){ + callback(); + }); + }, + + _load: function(callback){ + this.actions._load(function(){ + callback(); + }); + } +}); + + +// summary: +// A class that records actions taken by a user when they are offline, +// suitable for replaying when the network reappears. +// description: +// The basic idea behind this method is to record user actions that would +// normally have to contact a server into an action log when we are +// offline, so that later when we are online we can simply replay this log +// in the order user actions happened so that they can be executed against +// the server, causing synchronization to happen. +// +// When we replay, for each of the actions that were added, we call a +// method named onReplay that applications should connect to and +// which will be called over and over for each of our actions -- +// applications should take the offline action +// information and use it to talk to a server to have this action +// actually happen online, 'syncing' themselves with the server. +// +// For example, if the action was "update" with the item that was updated, we +// might call some RESTian server API that exists for updating an item in +// our application. The server could either then do sophisticated merging +// and conflict resolution on the server side, for example, allowing you +// to pop up a custom merge UI, or could do automatic merging or nothing +// of the sort. When you are finished with this particular action, your +// application is then required to call continueReplay() on the actionLog object +// passed to onReplay() to continue replaying the action log, or haltReplay() +// with the reason for halting to completely stop the syncing/replaying +// process. +// +// For example, imagine that we have a web application that allows us to add +// contacts. If we are offline, and we update a contact, we would add an action; +// imagine that the user has to click an Update button after changing the values +// for a given contact: +// +// dojox.off.whenOffline(dojo.byId("updateButton"), "onclick", function(evt){ +// // get the updated customer values +// var customer = getCustomerValues(); +// +// // we are offline -- just record this action +// var action = {name: "update", customer: customer}; +// dojox.off.sync.actions.add(action) +// +// // persist this customer data into local storage as well +// dojox.storage.put(customer.name, customer); +// }) +// +// Then, when we go back online, the dojox.off.sync.actions.onReplay event +// will fire over and over, once for each action that was recorded while offline: +// +// dojo.connect(dojox.off.sync.actions, "onReplay", function(action, actionLog){ +// // called once for each action we added while offline, in the order +// // they were added +// if(action.name == "update"){ +// var customer = action.customer; +// +// // call some network service to update this customer +// dojo.xhrPost({ +// url: "updateCustomer.php", +// content: {customer: dojo.toJson(customer)}, +// error: function(err){ +// actionLog.haltReplay(err); +// }, +// load: function(data){ +// actionLog.continueReplay(); +// } +// }) +// } +// }) +// +// Note that the actions log is always automatically persisted locally while using it, so +// that if the user closes the browser or it crashes the actions will safely be stored +// for later replaying. +dojo.declare("dojox.off.sync.ActionLog", null, { + // entries: Array + // An array of our action entries, where each one is simply a custom + // object literal that were passed to add() when this action entry + // was added. + entries: [], + + // reasonHalted: String + // If we halted, the reason why + reasonHalted: null, + + // isReplaying: boolean + // If true, we are in the middle of replaying a command log; if false, + // then we are not + isReplaying: false, + + // autoSave: boolean + // Whether we automatically save the action log after each call to + // add(); defaults to true. For applications that are rapidly adding + // many action log entries in a short period of time, it can be + // useful to set this to false and simply call save() yourself when + // you are ready to persist your command log -- otherwise performance + // could be slow as the default action is to attempt to persist the + // actions log constantly with calls to add(). + autoSave: true, + + add: function(action /* Object */){ /* void */ + // summary: + // Adds an action to our action log + // description: + // This method will add an action to our + // action log, later to be replayed when we + // go from offline to online. 'action' + // will be available when this action is + // replayed and will be passed to onReplay. + // + // Example usage: + // + // dojox.off.sync.log.add({actionName: "create", itemType: "document", + // {title: "Message", content: "Hello World"}}); + // + // The object literal is simply a custom object appropriate + // for our application -- it can be anything that preserves the state + // of a user action that will be executed when we go back online + // and replay this log. In the above example, + // "create" is the name of this action; "documents" is the + // type of item this command is operating on, such as documents, contacts, + // tasks, etc.; and the final argument is the document that was created. + + if(this.isReplaying){ + throw "Programming error: you can not call " + + "dojox.off.sync.actions.add() while " + + "we are replaying an action log"; + } + + this.entries.push(action); + + // save our updated state into persistent + // storage + if(this.autoSave){ + this._save(); + } + }, + + onReplay: function(action /* Object */, + actionLog /* dojox.off.sync.ActionLog */){ /* void */ + // summary: + // Called when we replay our log, for each of our action + // entries. + // action: Object + // A custom object literal representing an action for this + // application, such as + // {actionName: "create", item: {title: "message", content: "hello world"}} + // actionLog: dojox.off.sync.ActionLog + // A reference to the dojox.off.sync.actions log so that developers + // can easily call actionLog.continueReplay() or actionLog.haltReplay(). + // description: + // This callback should be connected to by applications so that + // they can sync themselves when we go back online: + // + // dojo.connect(dojox.off.sync.actions, "onReplay", function(action, actionLog){ + // // do something + // }) + // + // When we replay our action log, this callback is called for each + // of our action entries in the order they were added. The + // 'action' entry that was passed to add() for this action will + // also be passed in to onReplay, so that applications can use this information + // to do their syncing, such as contacting a server web-service + // to create a new item, for example. + // + // Inside the method you connected to onReplay, you should either call + // actionLog.haltReplay(reason) if an error occurred and you would like to halt + // action replaying or actionLog.continueReplay() to have the action log + // continue replaying its log and proceed to the next action; + // the reason you must call these is the action you execute inside of + // onAction will probably be asynchronous, since it will be talking on + // the network, and you should call one of these two methods based on + // the result of your network call. + }, + + length: function(){ /* Number */ + // summary: + // Returns the length of this + // action log + return this.entries.length; + }, + + haltReplay: function(reason /* String */){ /* void */ + // summary: Halts replaying this command log. + // reason: String + // The reason we halted. + // description: + // This method is called as we are replaying an action log; it + // can be called from dojox.off.sync.actions.onReplay, for + // example, for an application to indicate an error occurred + // while replaying this action, halting further processing of + // the action log. Note that any action log entries that + // were processed before have their effects retained (i.e. + // they are not rolled back), while the action entry that was + // halted stays in our list of actions to later be replayed. + if(!this.isReplaying){ + return; + } + + if(reason){ + this.reasonHalted = reason.toString(); + } + + // save the state of our action log, then + // tell anyone who is interested that we are + // done when we are finished saving + if(this.autoSave){ + var self = this; + this._save(function(){ + self.isReplaying = false; + self.onReplayFinished(); + }); + }else{ + this.isReplaying = false; + this.onReplayFinished(); + } + }, + + continueReplay: function(){ /* void */ + // summary: + // Indicates that we should continue processing out list of + // actions. + // description: + // This method is called by applications that have overridden + // dojox.off.sync.actions.onReplay() to continue replaying our + // action log after the application has finished handling the + // current action. + if(!this.isReplaying){ + return; + } + + // shift off the old action we just ran + this.entries.shift(); + + // are we done? + if(!this.entries.length){ + // save the state of our action log, then + // tell anyone who is interested that we are + // done when we are finished saving + if(this.autoSave){ + var self = this; + this._save(function(){ + self.isReplaying = false; + self.onReplayFinished(); + }); + return; + }else{ + this.isReplaying = false; + this.onReplayFinished(); + return; + } + } + + // get the next action + var nextAction = this.entries[0]; + this.onReplay(nextAction, this); + }, + + clear: function(){ /* void */ + // summary: + // Completely clears this action log of its entries + + if(this.isReplaying){ + return; + } + + this.entries = []; + + // save our updated state into persistent + // storage + if(this.autoSave){ + this._save(); + } + }, + + replay: function(){ /* void */ + // summary: + // For advanced usage; most developers can ignore this. + // Replays all of the commands that have been + // cached in this command log when we go back online; + // onCommand will be called for each command we have + + if(this.isReplaying){ + return; + } + + this.reasonHalted = null; + + if(!this.entries.length){ + this.onReplayFinished(); + return; + } + + this.isReplaying = true; + + var nextAction = this.entries[0]; + this.onReplay(nextAction, this); + }, + + // onReplayFinished: Function + // For advanced usage; most developers can ignore this. + // Called when we are finished replaying our commands; + // called if we have successfully exhausted all of our + // commands, or if an error occurred during replaying. + // The default implementation simply continues the + // synchronization process. Connect to this to register + // for the event: + // + // dojo.connect(dojox.off.sync.actions, "onReplayFinished", + // someFunc) + onReplayFinished: function(){ + }, + + toString: function(){ + var results = ""; + results += "["; + + for(var i = 0; i < this.entries.length; i++){ + results += "{"; + for(var j in this.entries[i]){ + results += j + ": \"" + this.entries[i][j] + "\""; + results += ", "; + } + results += "}, "; + } + + results += "]"; + + return results; + }, + + _save: function(callback){ + if(!callback){ + callback = function(){}; + } + + try{ + var self = this; + var resultsHandler = function(status, key, message){ + //console.debug("resultsHandler, status="+status+", key="+key+", message="+message); + if(status == dojox.storage.FAILED){ + dojox.off.onFrameworkEvent("save", + {status: dojox.storage.FAILED, + isCoreSave: true, + key: key, + value: message, + namespace: dojox.off.STORAGE_NAMESPACE}); + callback(); + }else if(status == dojox.storage.SUCCESS){ + callback(); + } + }; + + dojox.storage.put("actionlog", this.entries, resultsHandler, + dojox.off.STORAGE_NAMESPACE); + }catch(exp){ + console.debug("dojox.off.sync._save: " + exp.message||exp); + dojox.off.onFrameworkEvent("save", + {status: dojox.storage.FAILED, + isCoreSave: true, + key: "actionlog", + value: this.entries, + namespace: dojox.off.STORAGE_NAMESPACE}); + callback(); + } + }, + + _load: function(callback){ + var entries = dojox.storage.get("actionlog", dojox.off.STORAGE_NAMESPACE); + + if(!entries){ + entries = []; + } + + this.entries = entries; + + callback(); + } + } +); + +dojox.off.sync.actions = new dojox.off.sync.ActionLog(); + +} |