View source for 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 [[Labs/Weave/ClientAPI|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 <tt>weave/modules/engines</tt> 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 <tt>Engine</tt> (defined in <tt>weave/modules/engines.js</tt>).  This is pretty simple: it just needs <tt>name()</tt>, <tt>logName()</tt>, and <tt>serverPrefix()</tt> methods that return strings.

Your subclass also needs an attribute <tt>_core</tt> which is a <tt>SyncCore</tt> subclass object, an attribute <tt>_store</tt> which is a <tt>Store</tt> subclass object, and finally <tt>_tracker</tt> which is a <tt>Tracker</tt> 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 <tt>EXPORTED_SYMBOLS</tt> at the top of your file.

== Create your Store ==

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

Your <tt>Store</tt> 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:

* <tt>wrap()</tt>: 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.

* <tt>wipe()</tt>: should remove and delete all data from the local store, and return nothing.

* <tt>resetGUIDs()</tt>: 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 <tt>BookmarkStore.resetGUIDs()</tt> in <tt>weave/modules/engines/bookmarks.js</tt> for an example of how this should work. May not be necessary for all types of engines.

* <tt>_createCommand(command)</tt>, <tt>_removeCommand(command)</tt>, and <tt>_editCommand(command)</tt>: are called by the synchronization algorithm, in order to update the contents of your store.  The <tt>command</tt> 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:

::* <tt>GUID</tt>: 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 <tt>wrap()</tt>.

::* <tt>data</tt>: in the case of <tt>_createCommand()</tt> and <tt>_editCommand()</tt>, this contains the new data to be applied to the store.

== Create your SyncCore ==

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

It needs to implement these methods:

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

* <tt>_commandLike(a, b)</tt>: is passed two command objects as arguments.  It should return <tt>true</tt> 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 <tt>BookmarkSyncCore._commandLike()</tt> in <tt>weave/modules/engines/bookmarks.js</tt> 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 <tt>Tracker</tt> (defined in <tt>weave/modules/trackers.js</tt>).

The <tt>Tracker</tt> class has a getter method <tt>score()</tt> that simply returns the <tt>_score</tt> property. In your subclass, you may either choose to override the getter, or simply update the <tt>_score</tt> 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 <tt>resetScore()</tt>, which is called immediately after the service has synced the engine. The default behavior of this method sets <tt>_score</tt> 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 <tt>Engine</tt> subclass is instantiated and registered in <tt>weave/modules/services.js</tt>, in the function <tt>WeaveSvc()</tt>.  Look for where the existing engines are registered (to <tt>Engines.register</tt>) and add yours.

The last thing is to add your new data type to the Weave preferences UI.  Look in <tt>weave/chrome/content/preferences.xul</tt> for the boolean preferences called <tt>extensions.weave.bookmarks</tt>, <tt>extensions.weave.history</tt>, 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 <tt>weave/chrome/local/en-US/preferences.dtd</tt>.  Create an entity here with a name corresponding to what you used in <tt>preferences.xul</tt>, and with an appropriate value for the label string.

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