kopia lustrzana https://github.com/miklobit/TiddlyWiki5
161 wiersze
5.4 KiB
Plaintext
161 wiersze
5.4 KiB
Plaintext
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 |
|