This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/dev/

SyncAdaptorModules

25th October 2020 at 4:24pm
dev moduletypes

Introduction

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

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

See this pull request for background on the evolution of this API.

Exports

The following properties should be exposed via the exports object:

PropertyDescription
adaptorClassThe 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.

ParameterDescription
optionsSee 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.

ParameterDescription
tiddlerTarget tiddler

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

getTiddlerRevision(title)

Gets the revision ID associated with the specified tiddler title.

ParameterDescription
titleTiddler title

Returns a revision ID.

getStatus(callback)

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

ParameterDescription
callbackCallback 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.

ParameterDescription
usernameUsername
passwordPassword
callbackCallback function invoked with parameter err

displayLoginPrompt(syncer)

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

ParameterDescription
syncerReference 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.

ParameterDescription
callbackCallback 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.

ParameterDescription
syncerReference to the syncer object making the call
callbackCallback 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.

ParameterDescription
callbackCallback function invoked with parameter err,tiddlers, where tiddlers is an array of tiddler field objects

saveTiddler(tiddler,callback)

Saves a tiddler to the server.

ParameterDescription
tiddlerTiddler to be saved
callbackCallback function invoked with parameter err,adaptorInfo,revision
tiddlerInfoThe tiddlerInfo maintained by the syncer for this tiddler

loadTiddler(title,callback)

Loads a tiddler from the server.

ParameterDescription
titleTitle of tiddler to be retrieved
callbackCallback function invoked with parameter err,tiddlerFields

deleteTiddler(title,callback,options)

Delete a tiddler from the server.

ParameterDescription
titleTitle of tiddler to be deleted
callbackCallback function invoked with parameter err
optionsSee below

The options parameter contains the following properties:

PropertyDescription
tiddlerInfoThe tiddlerInfo maintained by the syncer for this tiddler