CloudServices/Sync/FxSync/Archived/AddDataType

THIS PAGE IS DEPRECATED. The API described below was for the 0.2 Weave client. It is obsolete and has been replaced. I'm leaving this page here for historical reference, but if you are extending Weave to sync a new data type, then you should be reading the new 0.3 Client API documentation page instead.

Back to Labs/Weave.

Adding support for a new data type

Create a new JavaScript file

The first thing you'll want to do is create a new JS file in the weave/modules/engines directory. You may just want to copy one of the existing files in that directory, as they will contain a decent template for you to get started.

Create your Engine

In your file, add a new subclass of Engine (defined in weave/modules/engines.js). This is pretty simple: it just needs name(), logName(), and serverPrefix() methods that return strings.

Your subclass also needs an attribute _core which is a SyncCore subclass object, an attribute _store which is a Store subclass object, and finally _tracker which is a Tracker subclass object. Don't worry about these just yet--you'll be creating their implementations in a moment.

Make sure to add the name of your new engine to EXPORTED_SYMBOLS at the top of your file.

Create your Store

In your file, you'll need to add a new subclass of Store (defined in weave/modules/stores.js).

Your Store subclass can store the user data however you see fit, as long as it provides the right interface. You need to implement the following methods:

• wrap(): should return a JSON representation of all the data that is being stored. The top-level structure of the JSON is a dictionary, where each value is a representation of one object from the user data store, and the key for that value is a GUID.

• wipe(): should remove and delete all data from the local store, and return nothing.

• resetGUIDs(): is called in the case where the GUIDs of the local store have gotten out of sync with the GUIDs on the server, so that there's some kind of GUID conflict. See the implementation of BookmarkStore.resetGUIDs() in weave/modules/engines/bookmarks.js for an example of how this should work. May not be necessary for all types of engines.

• _createCommand(command), _removeCommand(command), and _editCommand(command): are called by the synchronization algorithm, in order to update the contents of your store. The command argument passed to each one is an object describing what user data should be created in the store, removed from the store, or updated within the store, respectively. It contains the following properties:

• GUID: this uniquely identifies which item in the store is to be affected. It will correspond to the GUID keys of the JSON dictionary that you return from wrap().

• data: in the case of _createCommand() and _editCommand(), this contains the new data to be applied to the store.

Create your SyncCore

In your file, create a subclass of SyncCore (defined in weave/modules/syncCores.js).

It needs to implement these methods:

• _itemExists(GUID): should return true if a data object of the given GUID exists on the system (i.e. in the corresponding Store), false otherwise.

• _commandLike(a, b): is passed two command objects as arguments. It should return true if the two commands are determined to refer to the same thing. This is meant to eliminate duplicate or redundant commands. See the implementation of BookmarkSyncCore._commandLike() in weave/modules/engines/bookmarks.js for inspiration.

Create your Tracker

The Weave service periodically queries each of its registered engines via its tracker to decide whether that particular engine needs to be synced or not. In your file, you'll need to create a subclass of Tracker (defined in weave/modules/trackers.js).

The Tracker class has a getter method score() that simply returns the _score property. In your subclass, you may either choose to override the getter, or simply update the _score property in an Observer. Which method you choose is dependent on the engine, but the idea is to return a number between 0 and 100 whenever the weave service uses the getter. 0 means there has been no change in your data source, 100 means that your engine really needs to sync ASAP. A special value of -1 is also recognized; it means the service doesn't need to sync unless the user explicitly requests it (useful for engines like Session/Tab restore). Note that a value of 0 means the service will not try to sync even if it was explicitly requested by the user (because there is nothing to sync).

The other important method is resetScore(), which is called immediately after the service has synced the engine. The default behavior of this method sets _score to 0, but you may choose to override it and do something else.

You are encouraged take a look at the existing trackers to get an idea of how they are implemented.

Final touches

Once you've created all your classes, you'll need to make sure that your Engine subclass is instantiated and registered in weave/modules/services.js, in the function WeaveSvc(). Look for where the existing engines are registered (to Engines.register) and add yours.

The last thing is to add your new data type to the Weave preferences UI. Look in weave/chrome/content/preferences.xul for the boolean preferences called extensions.weave.bookmarks, extensions.weave.history, and so on. They're boolean preferences because they're checkboxes which turn synchronization of a given data type on or off. Add one for your data type using the existing XUL tags as a model.

The text labels for the checkboxes in the preferences GUI are defined in a separate file to make localization easier. The file for US English is weave/chrome/local/en-US/preferences.dtd. Create an entity here with a name corresponding to what you used in preferences.xul, and with an appropriate value for the label string.

Finally, set the default value of your preference in defaults/preferences/sync.js.