TiddlyWiki5/editions/dev/tiddlers/from tw5.com/moduletypes/SyncAdaptorModules.tid

created: 20130825162100000
modified: 20201025162413404
tags: dev moduletypes
title: SyncAdaptorModules
type: text/vnd.tiddlywiki

! Introduction

SyncAdaptorModules encapsulate storage mechanisms that can be used by the SyncMechanism. Two examples are:

* The TiddlyWebAdaptor interfaces with servers compatible with TiddlyWeb's HTTP API, such as TiddlyWeb itself and TiddlyWiki5's built-in ServerMechanism.

* The LocalFileAdaptor interfaces with file systems with an API compatible with Node.js's `fs` module

SyncAdaptorModules are represented as JavaScript tiddlers with the field `module-type` set to `syncadaptor`.

See [[this pull request|https://github.com/Jermolene/TiddlyWiki5/pull/4373]] for background on the evolution of this API.

! Exports

The following properties should be exposed via the `exports` object:

|!Property |!Description |
|adaptorClass |The JavaScript class for the adaptor |

Nothing should be exported if the adaptor detects that it isn't capable of operating successfully (eg, because it only runs on either the browser or the server, or because a dependency is missing).

! Adaptor Module Methods

Adaptor modules must handle the methods described below.

!!! Error Handling

The syncadaptor must invoke the provided callback with the ''err'' parameter containing a string describing the error.

The syncer has special handling for connection errors. For backwards compatibilty reasons, the syncer identifies connection errors as the string comprised of the content of the tiddler $:/language/Error/XMLHttpRequest with the string ": 0" appended to the end. For example, in English, the string is "XMLHttpRequest error code: 0" and in Brazilian Portuguese it is "Código de erro XMLHttpRequest: 0".

!! `Constructor(options)`

Initialises a new adaptor instance.

|!Parameter |!Description |
|options |See below |

Options include:

* ''options.wiki'': reference to wiki to use with this syncadaptor

!! `getTiddlerInfo(tiddler)`

Gets the supplemental information that the adaptor needs to keep track of for a particular tiddler. For example, the TiddlyWeb adaptor includes a `bag` field indicating the original bag of the tiddler.

|!Parameter |!Description |
|tiddler |Target tiddler |

Returns an object storing any additional information required by the adaptor.

!! `getTiddlerRevision(title)`

Gets the revision ID associated with the specified tiddler title.

|!Parameter |!Description |
|title |Tiddler title |

Returns a revision ID.

!! `getStatus(callback)`

Retrieves status information from the server. This method is optional.

|!Parameter |!Description |
|callback |Callback function invoked with parameters `err,isLoggedIn,username,isReadOnly` |

!! `login(username,password,callback)`

Attempts to login to the server with specified credentials. This method is optional.

|!Parameter |!Description |
|username |Username |
|password |Password |
|callback |Callback function invoked with parameter `err` |

!! `displayLoginPrompt(syncer)`

Invoked by the syncer to display a custom login prompt. This method is optional.

|!Parameter |!Description |
|syncer |Reference to the syncer object making the call |

The custom login prompt should send the widget message `tm-login` with the username and password in parameters ''username'' and ''password''.

!! `logout(callback)`

Attempts to logout of the server. This method is optional.

|!Parameter |!Description |
|callback |Callback function invoked with parameter `err` |

!! `getUpdatedTiddlers(syncer,callback)`

Retrieves the titles of tiddlers that need to be updated from the server.

This method is optional. If an adaptor doesn't implement it then synchronisation will be unidirectional from the TiddlyWiki store to the adaptor, but not the other way.

The syncer will use the `getUpdatedTiddlers()` method in preference to the `getSkinnyTiddlers()` method.

|!Parameter |!Description |
|syncer |Reference to the syncer object making the call |
|callback |Callback function invoked with parameter `err,data` -- see below |

The data provided by the callback is as follows:

```
{
modifications: [<array of title>],
deletions: [<array of title>],
}
```

!! `getSkinnyTiddlers(callback)`

Retrieves a list of skinny tiddlers from the server.

This method is optional. If an adaptor doesn't implement it then synchronisation will be unidirectional from the TiddlyWiki store to the adaptor, but not the other way.

The syncer will use the `getUpdatedTiddlers()` method in preference to the `getSkinnyTiddlers()` method.

|!Parameter |!Description |
|callback |Callback function invoked with parameter `err,tiddlers`, where `tiddlers` is an array of tiddler field objects |

!! `saveTiddler(tiddler,callback)`

Saves a tiddler to the server.

|!Parameter |!Description |
|tiddler |Tiddler to be saved |
|callback |Callback function invoked with parameter `err,adaptorInfo,revision` |
|tiddlerInfo |The tiddlerInfo maintained by the syncer for this tiddler |

!! `loadTiddler(title,callback)`

Loads a tiddler from the server.

|!Parameter |!Description |
|title |Title of tiddler to be retrieved |
|callback |Callback function invoked with parameter `err,tiddlerFields` |

!! `deleteTiddler(title,callback,options)`

Delete a tiddler from the server.

|!Parameter |!Description |
|title |Title of tiddler to be deleted |
|callback |Callback function invoked with parameter `err` |
|options |See below |

The options parameter contains the following properties:

|!Property |!Description |
|tiddlerInfo |The tiddlerInfo maintained by the syncer for this tiddler |