Name: sync-cordova-plugin
Owner: Cloudant
Description: Cordova plugin for Cloudant Sync for Android and iOS
Created: 2015-09-14 14:39:43.0
Updated: 2018-05-23 12:33:49.0
Pushed: 2018-05-23 12:33:50.0
Homepage: null
Size: 20766
Language: Objective-C
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
Applications use Cloudant Sync to store, index and query local JSON data on a device and to synchronise data between many devices. Synchronisation is under the control of the application, rather than being controlled by the underlying system. Conflicts are also easy to manage and resolve, either on the local device or in the remote database.
Cloudant Sync is an Apache CouchDB™ replication-protocol-compatible datastore for devices that don't want or need to run a full CouchDB instance. It's built by Cloudant, building on the work of many others, and is available under the Apache 2.0 licence.
The API is quite different from CouchDB's; we retain the MVCC data model but not the HTTP-centric API.
This is a Cordova plugin which wraps our iOS and Android libraries.
Add this plugin to your project via the Cordova CLI. Optionally append the
--save argument to persist the changes in your application's config.xml.
$ cordova plugin add https://github.com/cloudant/sync-cordova-plugin#VERSION
where VERSION should be replaced by a released version of the
sync-cordova-plugin, e.g.:
$ cordova plugin add https://github.com/cloudant/sync-cordova-plugin#0.3.0
Note that you should always specify a released version. Failure to do so would mean you may be working with an unreleased version of the plugin that may not be stable.
Add Android as a platform
rdova platform add android
Set the environment variable ANDROID_BUILD to gradle (e.g. on mac this is export ANDROID_BUILD=gradle)
Add iOS as a platform
rdova platform add ios
To run the cordova app on an iOS device, the following steps are necessary:
platforms/ios subdirectory).CocoaLumberjack.framework, CDTDatastore.framework, FMDB.framework.CocoaLumberjack.framework, CDTDatastore.framework, FMDB.framework.
Note that this step adds these frameworks back to “Linked Frameworks and Libraries”
as well as adding them to “Embedded Binaries”. The libraries should be left in both
sections. Their removal in the previous step is simply to prevent each framework appearing
twice in “Linked Frameworks and Libraries”.Shared Frameworks.cordova run ios.cordova run ios.Once the plugin has been added to a project, the basics are:
Opening a Datastore
DatastoreManager = cordova.require('cloudant-sync.DatastoreManager');
datastore;
storeManager.DatastoreManager().then(function(datastoreManager) {
return datastoreManager.openDatastore('my_datastore');
hen(function(my_datastore){
datastore = my_datastore;
one();
Creating documents
revision = {
animal: "cat"
store.createDocumentFromRevision(revision)
.then(function(saved) {
}).done();
Add a file attachment
image = 'base64 encoded string';
d._attachments = {
image: {
content_type: 'image/jpeg',
data: image
}
store.updateDocumentFromRevision(saved)
.then(function (updated) {
}).done();
Read a document
store.getDocument(updated._id)
.then(function (fetchedRevision) {
}).done();
Read more in the CRUD document.
Replication is used to synchronise data between the local datastore and a remote database, either a CouchDB instance or a Cloudant database. Many datastores can replicate with the same remote database, meaning that cross-device synchronisation is achieved by setting up replications from each device the remote database.
Replication is simple to get started in the common cases:
Replicator = cordova.require('cloudant-sync.Replicator');
uri = 'https://apikey:apipasswd@username.cloudant.com/my_database';
ptions object to create a pull replicator
pullReplicatorOptions = {
source: uri,
target: datastore
eplicate from the remote to local database
icator.create(pullReplicatorOptions).then(function (replicator) {
replicator.start(); // Fire-and-forget (there are easy ways to monitor the state too)
one();
Read more in the replication docs.
Once you have thousands of documents in a database, it's important to have efficient ways of finding them. We've added an easy-to-use querying API. Once the appropriate indexes are set up, querying is as follows:
query = {
selector: {
name: 'mike',
pet: 'cat'
}
store.find(query)
.then(function (results) {
results.forEach(function (revision) {
// do something
});
}).done();
An obvious repercussion of being able to replicate documents about the place is that sometimes you might edit them in more than one place at the same time. When the databases containing these concurrent edits replicate, there needs to be some way to bring these divergent documents back together. Cloudant's MVCC data-model is used to do this.
A document is really a tree of the document and its history. This is neat because it allows us to store multiple versions of a document. In the main, there's a single, linear tree – just a single branch – running from the creation of the document to the current revision. It's possible, however, to create further branches in the tree. At this point your document is conflicted and needs some surgery to resolve the conflicts and bring it back to full health.
Learn more about this essential process in the conflicts documentation.
Nested JSON elements do not work correctly on Android API levels <19. This is because the
JsonObject#wrap()
used internally in the platform is only available since API level 19.
If you have no nested JSON elements the minimum API level is 16.
See CONTRIBUTORS.
See CONTRIBUTING.
See LICENSE.