+++ /dev/null
-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();
-
-}
projects / eow / blobdiff